From 346189cf4cb52400b4479e55b3233b861890c302 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Thu, 23 Aug 2018 16:50:47 +0200
Subject: [PATCH 01/17] Draft

---
 docs/reference/swagger.yaml | 221 +++++++++++++++++++++++++++++++++---
 1 file changed, 205 insertions(+), 16 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 26848826..11f41b77 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -36,11 +36,11 @@ tags:
     externalDocs:
       url: 'https://carto.com/developers/maps-api/guides/anonymous-maps/'
   - name: Named Maps
-    description: Run a single SQL statement
+    description: Instantiate a map from private data, and users without an API Key can view your Named Map.
     externalDocs:
       url: 'https://carto.com/developers/maps-api/guides/named-maps/'
   - name: Static Maps
-    description: Create static images of parts of maps
+    description: Create static images of parts of maps and thumbnails for use in web design, graphic design, print, field work, and many other applications that require standard image formats.
     externalDocs:
       url: 'https://carto.com/developers/maps-api/guides/static-maps-API/'
 paths:
@@ -88,7 +88,7 @@ paths:
             curl -X POST -H "Content-Type: application/json" -d '{ \
               "q": "SELECT count(*) FROM cities", \
               "filename": "number_of_cities.json" \
-            }' "https://username.carto.com/api/v2/sql"      
+            }' "https://username.carto.com/api/v2/sql"
   '/map/{layergroupid}/{z}/{x}/{y}.png':
     get:
       parameters:
@@ -197,7 +197,113 @@ paths:
             curl -X GET \
 
             https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png
-
+  'map/named':
+    post:
+      summary: Upload template
+      description: |
+      tags:
+        - Named Maps
+      security:
+        - ApiKeyHTTPBasicAuth: []
+        - ApiKeyQueryParam: []
+      operationId: instantiateAnonymousMap
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Template'
+            example:
+              version: 0.0.1
+              name: 'template_name'
+              auth:
+                method: 'token'
+                valid_tokens:
+                  - 'auth_token1'
+                  - 'auth_token2'
+              placeholders:
+                color:
+                  type: 'css_color'
+                  default: 'red'
+                cartodb_id:
+                  type: 'number'
+                  default: 1
+              layergroup:
+                version: 1.7.0
+                layers:
+                  - type: mapnik
+                    options:
+                      cartocss_version: 2.1.1
+                      cartocss: '#layer { polygon-fill: #FFF; }'
+                      sql: select * from european_countries_e
+                      interactivity:
+                        - cartodb_id
+                        - iso3
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NamedMapResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X POST -H "Content-Type: application/json" -d '{ \
+              "version": "0.0.1", \
+              "name": "template_name", \
+              "auth": { \
+                "method": "token", \
+                "valid_tokens": [ \
+                  "auth_token1", \
+                  "auth_token2" \
+                ] \
+              }, \
+              "placeholders": { \
+                "color": { \
+                  "type": "css_color", \
+                  "default": "red" \
+                }, \
+                "cartodb_id": { \
+                  "type": "number", \
+                  "default": 1 \
+                } \
+              }, \
+              "layergroup": { \
+                "version": "1.7.0", \
+                "layers": [ \
+                  { \
+                    "type": "cartodb", \
+                    "options": { \
+                      "cartocss_version": "2.3.0", \
+                      "cartocss": "#layer { polygon-fill: <%= color %>; }", \
+                      "sql": "select * from european_countries_e WHERE cartodb_id = <%= cartodb_id %>" \
+                    } \
+                  } \
+                ] \
+              }, \
+              "view": { \
+                "zoom": 4, \
+                "center": { \
+                  "lng": 0, \
+                  "lat": 0 \
+                }, \
+                "bounds": { \
+                  "west": -45, \
+                  "south": -45, \
+                  "east": 45, \
+                  "north": 45 \
+                }, \
+                "preview_layers": { \
+                  "0": true, \
+                  "layer1": false \
+                } \
+              } \
+            }' "https://{username}.carto.com/api/v1/map/named?api_key={api_key}"
   '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}':
     get:
       parameters:
@@ -237,7 +343,7 @@ paths:
             curl -X GET \
 
             https://username.carto.com/api/v1/map/static/center/c01a54877c62831bb51720263f91fb33/4/20/40/500/500.png
-            
+
   '/map/static/bbox/{layergroupid}/{west},{south},{east},{north}/{width}/{height}.{format}':
     get:
       parameters:
@@ -313,7 +419,7 @@ paths:
           source: >
             curl -X GET \
 
-            https://username.carto.com/api/map/static/named/mynamedmap/500/500.png  
+            https://username.carto.com/api/map/static/named/mynamedmap/500/500.png
 
 components:
   schemas:
@@ -382,7 +488,7 @@ components:
 
 
             **Tip:** The SQL request should include the following Mapnik layer
-            configurations: 
+            configurations:
               * ```geom_column```
               * ```interactivity```
               * ```attributes```
@@ -425,7 +531,7 @@ components:
 
 
             **Note:** If the default, or no value is specified, raster bands are
-            interpreted as either: 
+            interpreted as either:
               * grayscale (for single bands)
               * RGB (for 3 bands)
               * RGBA (for 4 bands).
@@ -490,7 +596,7 @@ components:
 
 
             **Tip:** The SQL request should include the following Mapnik layer
-            configurations: 
+            configurations:
               * geom_column
               * interactivity
               * attributes
@@ -551,7 +657,7 @@ components:
           type: string
           description: >
             URL from where the tile data is retrieved. _URLs must be included in
-            the configuration whitelist to be valid._ 
+            the configuration whitelist to be valid._
 
 
             **Note:** It includes
@@ -609,8 +715,8 @@ components:
 
               - An integer array of r,g,b,a values (i.e. ```[255,0,0,128]```)
 
-              
-              
+
+
             If **only** the ```color``` value is used for a plain layer, this
             value is Required.
 
@@ -724,6 +830,89 @@ components:
               type: string
             https:
               type: string
+    Template:
+      type: object
+      properties:
+        version:
+          type: string
+          description: Spec version to use for validation.
+          default: 0.0.1
+        name:
+          type: string
+          description: There can only be one template with the same name for any user. Valid names start with a letter or a number, and only contain letters, numbers, dashes (-), or underscores (_)
+        auth:
+          type: object
+          properties:
+            method:
+              type: string
+              description: token or open
+              default: open
+            valid_tokens:
+              type: array
+              description: when `"method"` is set to `"token"`, the values listed here allow you to instantiate the Named Map. See this [example](http://docs.carto.com/faqs/manipulating-your-data/#how-to-create-a-password-protected-named-map) for how to create a password-protected map.
+        placeholders:
+          type: object
+          description: >
+            Variables that can be placed in layergroup's definition (SQL or CartoCSS of any layer). Placeholders need to be defined with a `type` and a default value for MapConfigs. See details about defining a MapConfig `type` for [Layergroup configurations](http://docs.carto.com/carto-engine/maps-api/mapconfig/#layergroup-configurations).
+
+            Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced inside the Named Maps API.
+
+            ```javascript
+            <%= my_color %>
+            ````
+
+            The set of supported placeholders for a template need to be explicitly defined with a specific type, and default value, for each placeholder.
+
+            The placeholder type will determine the kind of escaping for the associated value. Supported types are:
+
+            Types | Description
+            --- | ---
+            sql_literal | internal single-quotes will be sql-escaped
+            sql_ident | internal double-quotes will be sql-escaped
+            number | can only contain numerical representation
+            css_color | can only contain color names or hex-values
+
+            Placeholder default values will be used whenever new values are not provided as options, at the time of creation on the client. They can also be used to test the template by creating a default version with new options provided.
+
+            When using templates, be very careful about your selections as they can give broad access to your data if they are defined loosely.
+          example: <%= my_color %>
+        layergroup:
+          type: object
+          description: The layergroup configurations, as specified in the template. See [MapConfig File Format](http://docs.carto.com/carto-engine/maps-api/mapconfig/) for more information
+        view:
+          type: object
+          description: Extra keys to specify the view area for the map. It can be used to have a static preview of a Named Map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box. Also it is possible to choose which layers are visible or not with `preview_layers` indicating its visibility by layer index or id (visible by default).
+          properties:
+            zoom:
+              type: number
+              description: The zoom level to use
+            center:
+              type: object
+              properties:
+                lng:
+                  type: number
+                  description: The longitude to use for the center
+                lat:
+                  type: number
+                  description: The latitude to use for the center
+            bounds:
+              type: object
+              properties:
+                west: LowerCorner longitude for the bounding box, in decimal degrees (aka most western)
+                south: LowerCorner latitude for the bounding box, in decimal degrees (aka most southern)
+                east: UpperCorner longitude for the bounding box, in decimal degrees (aka most eastern)
+                north: UpperCorner latitude for the bounding box, in decimal degrees (aka most northern)
+      required:
+        - version
+        - name
+        - auth
+        - placeholders
+        - layergroup
+    NamedMapResponse:
+      type: object
+      properties:
+        template_id:
+          type: string
   securitySchemes:
     ApiKeyHTTPBasicAuth:
       type: http
@@ -817,7 +1006,7 @@ components:
       schema:
         type: number
         format: float
-      description: LowerCorner latitude, in decimal degrees (aka most southern) in WGS 84 (EPSG:4326)  
+      description: LowerCorner latitude, in decimal degrees (aka most southern) in WGS 84 (EPSG:4326)
     east:
       in: path
       name: east
@@ -825,7 +1014,7 @@ components:
       schema:
         type: number
         format: float
-      description: UpperCorner longitude, in decimal degrees (aka most eastern) in WGS 84 (EPSG:4326)  
+      description: UpperCorner longitude, in decimal degrees (aka most eastern) in WGS 84 (EPSG:4326)
     north:
       in: path
       name: north
@@ -833,7 +1022,7 @@ components:
       schema:
         type: number
         format: float
-      description: UpperCorner latitude, in decimal degrees (aka most northern) in WGS 84 (EPSG:4326) 
+      description: UpperCorner latitude, in decimal degrees (aka most northern) in WGS 84 (EPSG:4326)
     name:
       in: path
       name: name
@@ -856,7 +1045,7 @@ components:
         Layers to be rendered together.
 
         Supports 2 format options:
-        * a comma separated list of layer indexes (0-based). Examples: 
+        * a comma separated list of layer indexes (0-based). Examples:
 
           * **0,1,3** - will filter and blend layers with indexes 0, 1 and 3
           * **2** - only one layer

From e3f6d4e9fd8c7ef03e588c989a19f13197f70466 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Thu, 23 Aug 2018 17:19:45 +0200
Subject: [PATCH 02/17] Fix swagger errors

---
 docs/reference/swagger.yaml | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 11f41b77..6cef6f84 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -197,7 +197,7 @@ paths:
             curl -X GET \
 
             https://username.carto.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/2/3/4.png
-  'map/named':
+  '/map/named':
     post:
       summary: Upload template
       description: |
@@ -848,8 +848,8 @@ components:
               description: token or open
               default: open
             valid_tokens:
-              type: array
-              description: when `"method"` is set to `"token"`, the values listed here allow you to instantiate the Named Map. See this [example](http://docs.carto.com/faqs/manipulating-your-data/#how-to-create-a-password-protected-named-map) for how to create a password-protected map.
+              type: string
+              description: when method is set to token, the values listed here allow you to instantiate the Named Map. See this [example](http://docs.carto.com/faqs/manipulating-your-data/#how-to-create-a-password-protected-named-map) for how to create a password-protected map.
         placeholders:
           type: object
           description: >
@@ -897,11 +897,20 @@ components:
                   description: The latitude to use for the center
             bounds:
               type: object
+              description: View area for the map. It can be used to have a static preview with bounding box `bbox
               properties:
-                west: LowerCorner longitude for the bounding box, in decimal degrees (aka most western)
-                south: LowerCorner latitude for the bounding box, in decimal degrees (aka most southern)
-                east: UpperCorner longitude for the bounding box, in decimal degrees (aka most eastern)
-                north: UpperCorner latitude for the bounding box, in decimal degrees (aka most northern)
+                west:
+                  type: number
+                  description: LowerCorner longitude for the bounding box, in decimal degrees (aka most western)
+                south:
+                  type: number
+                  description: LowerCorner latitude for the bounding box, in decimal degrees (aka most southern)
+                east:
+                  type: number
+                  description: UpperCorner longitude for the bounding box, in decimal degrees (aka most eastern)
+                north:
+                  type: number
+                  description: UpperCorner latitude for the bounding box, in decimal degrees (aka most northern)
       required:
         - version
         - name

From 409170f661aafc0ce5cde3be53a189aedf3a14e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Thu, 23 Aug 2018 18:24:17 +0200
Subject: [PATCH 03/17] Create TemplatePlaceholders

---
 docs/reference/swagger.yaml | 51 +++++++++++++++++--------------------
 1 file changed, 24 insertions(+), 27 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 6cef6f84..c8d17c71 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -851,34 +851,9 @@ components:
               type: string
               description: when method is set to token, the values listed here allow you to instantiate the Named Map. See this [example](http://docs.carto.com/faqs/manipulating-your-data/#how-to-create-a-password-protected-named-map) for how to create a password-protected map.
         placeholders:
-          type: object
-          description: >
-            Variables that can be placed in layergroup's definition (SQL or CartoCSS of any layer). Placeholders need to be defined with a `type` and a default value for MapConfigs. See details about defining a MapConfig `type` for [Layergroup configurations](http://docs.carto.com/carto-engine/maps-api/mapconfig/#layergroup-configurations).
-
-            Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced inside the Named Maps API.
-
-            ```javascript
-            <%= my_color %>
-            ````
-
-            The set of supported placeholders for a template need to be explicitly defined with a specific type, and default value, for each placeholder.
-
-            The placeholder type will determine the kind of escaping for the associated value. Supported types are:
-
-            Types | Description
-            --- | ---
-            sql_literal | internal single-quotes will be sql-escaped
-            sql_ident | internal double-quotes will be sql-escaped
-            number | can only contain numerical representation
-            css_color | can only contain color names or hex-values
-
-            Placeholder default values will be used whenever new values are not provided as options, at the time of creation on the client. They can also be used to test the template by creating a default version with new options provided.
-
-            When using templates, be very careful about your selections as they can give broad access to your data if they are defined loosely.
-          example: <%= my_color %>
+          $ref: '#/components/schemas/TemplatePlaceholders'
         layergroup:
-          type: object
-          description: The layergroup configurations, as specified in the template. See [MapConfig File Format](http://docs.carto.com/carto-engine/maps-api/mapconfig/) for more information
+          $ref: '#/components/schemas/MapConfig'
         view:
           type: object
           description: Extra keys to specify the view area for the map. It can be used to have a static preview of a Named Map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box. Also it is possible to choose which layers are visible or not with `preview_layers` indicating its visibility by layer index or id (visible by default).
@@ -917,6 +892,28 @@ components:
         - auth
         - placeholders
         - layergroup
+    TemplatePlaceholders:
+      type: object
+      description: >
+        Variables that can be placed in layergroup's definition (SQL or CartoCSS of any layer). Placeholders need to be defined with a `type` and a default value for MapConfigs. See details about defining a MapConfig `type` for [Layergroup configurations](http://docs.carto.com/carto-engine/maps-api/mapconfig/#layergroup-configurations). Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced inside the Named Maps API.
+
+        **Example**:```<%= my_color %>```
+
+        The set of supported placeholders for a template need to be explicitly defined with a specific type, and default value, for each placeholder. Placeholder default values will be used whenever new values are not provided as options, at the time of creation on the client. They can also be used to test the template by creating a default version with new options provided. When using templates, be very careful about your selections as they can give broad access to your data if they are defined loosely.
+      properties:
+        type:
+          type: string
+          enum: [sql_literal, sql_ident, number, css_color]
+          description: >
+            sql_literal: internal single-quotes will be sql-escaped
+            sql_ident: internal double-quotes will be sql-escaped
+            number: can only contain numerical representation
+            css_color: can only contain color names or hex-values
+        default:
+          type: 'string or number or hex-value'
+      required:
+        - type
+        - default
     NamedMapResponse:
       type: object
       properties:

From 49d5f560a78ddf962bdcc8d9db9e3587ebb6a136 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Thu, 23 Aug 2018 19:07:13 +0200
Subject: [PATCH 04/17] Extract components

---
 docs/reference/swagger.yaml | 89 ++++++++++++++++++++++++-------------
 1 file changed, 57 insertions(+), 32 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index c8d17c71..e4200c05 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -855,37 +855,7 @@ components:
         layergroup:
           $ref: '#/components/schemas/MapConfig'
         view:
-          type: object
-          description: Extra keys to specify the view area for the map. It can be used to have a static preview of a Named Map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box. Also it is possible to choose which layers are visible or not with `preview_layers` indicating its visibility by layer index or id (visible by default).
-          properties:
-            zoom:
-              type: number
-              description: The zoom level to use
-            center:
-              type: object
-              properties:
-                lng:
-                  type: number
-                  description: The longitude to use for the center
-                lat:
-                  type: number
-                  description: The latitude to use for the center
-            bounds:
-              type: object
-              description: View area for the map. It can be used to have a static preview with bounding box `bbox
-              properties:
-                west:
-                  type: number
-                  description: LowerCorner longitude for the bounding box, in decimal degrees (aka most western)
-                south:
-                  type: number
-                  description: LowerCorner latitude for the bounding box, in decimal degrees (aka most southern)
-                east:
-                  type: number
-                  description: UpperCorner longitude for the bounding box, in decimal degrees (aka most eastern)
-                north:
-                  type: number
-                  description: UpperCorner latitude for the bounding box, in decimal degrees (aka most northern)
+          $ref: '#/components/schemas/TemplateView'
       required:
         - version
         - name
@@ -910,10 +880,65 @@ components:
             number: can only contain numerical representation
             css_color: can only contain color names or hex-values
         default:
-          type: 'string or number or hex-value'
+          type: string
       required:
         - type
         - default
+    TemplateView:
+      type: object
+      description: Extra keys to specify the view area for the map. It can be used to have a static preview of a Named Map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box. Also it is possible to choose which layers are visible or not with `preview_layers` indicating its visibility by layer index or id (visible by default).
+      properties:
+        zoom:
+          $ref: '#/components/schemas/TemplateViewZoom'
+        center:
+          $ref: '#/components/schemas/TemplateViewZoom'
+        bounds:
+          $ref: '#/components/schemas/TemplateViewBounds'
+        preview_layers:
+          $ref: '#/components/schemas/TemplateViewPreviewLayers'
+    TemplateViewZoom:
+      type: number
+      description: The zoom level to use
+      example: 4
+    TemplateViewCenter:
+      type: object
+      properties:
+        lng:
+          type: number
+          description: The longitude to use for the center
+        lat:
+          type: number
+          description: The latitude to use for the center
+      example:
+        lng: 0
+        lat: 0
+    TemplateViewBounds:
+      type: object
+      description: View area for the map. It can be used to have a static preview with bounding box `bbox
+      properties:
+        west:
+          type: number
+          description: LowerCorner longitude for the bounding box, in decimal degrees (aka most western)
+        south:
+          type: number
+          description: LowerCorner latitude for the bounding box, in decimal degrees (aka most southern)
+        east:
+          type: number
+          description: UpperCorner longitude for the bounding box, in decimal degrees (aka most eastern)
+        north:
+          type: number
+          description: UpperCorner latitude for the bounding box, in decimal degrees (aka most northern)
+      example:
+        west: -45
+        south: -45
+        east: 45
+        north: 45
+    TemplateViewPreviewLayers:
+      type: object
+      description: Indicates which layers are visible or not by layer index or id (visible by default).
+      example:
+        0: true
+        layer1: false
     NamedMapResponse:
       type: object
       properties:

From cd75581ccb6cd4b2d160c99ea82fe94f2bb19beb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 10:42:08 +0200
Subject: [PATCH 05/17] Add list template endpoint

---
 docs/reference/swagger.yaml | 49 +++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index e4200c05..57a27909 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -201,11 +201,9 @@ paths:
     post:
       summary: Upload template
       description: |
+        Upload template
       tags:
         - Named Maps
-      security:
-        - ApiKeyHTTPBasicAuth: []
-        - ApiKeyQueryParam: []
       operationId: instantiateAnonymousMap
       requestBody:
         required: true
@@ -250,6 +248,9 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyQueryParam: []
+        - ApiKeyHTTPBasicAuth: []
       x-code-samples:
         - lang: Curl
           source: |
@@ -304,6 +305,32 @@ paths:
                 } \
               } \
             }' "https://{username}.carto.com/api/v1/map/named?api_key={api_key}"
+    get:
+      summary: List user's templates
+      description: |
+        List user's templates
+      tags:
+        - Named Maps
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NamedMapResponseList'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyQueryParam: []
+        - ApiKeyHTTPBasicAuth: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X GET 'https://{username}.carto.com/api/v1/map/named?api_key={api_key}'
   '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}':
     get:
       parameters:
@@ -891,11 +918,15 @@ components:
         zoom:
           $ref: '#/components/schemas/TemplateViewZoom'
         center:
-          $ref: '#/components/schemas/TemplateViewZoom'
+          $ref: '#/components/schemas/TemplateViewCenter'
         bounds:
           $ref: '#/components/schemas/TemplateViewBounds'
         preview_layers:
           $ref: '#/components/schemas/TemplateViewPreviewLayers'
+      required:
+        - zoom
+        - center
+        - bounds
     TemplateViewZoom:
       type: number
       description: The zoom level to use
@@ -944,13 +975,21 @@ components:
       properties:
         template_id:
           type: string
+    NamedMapResponseList:
+      type: object
+      properties:
+        template_ids:
+          type: array
+          items:
+            type: string
+            description: template name
   securitySchemes:
     ApiKeyHTTPBasicAuth:
       type: http
       scheme: basic
     ApiKeyQueryParam:
       type: apiKey
-      in: header
+      in: query
       name: api_key
   parameters:
     layergroupId:

From 91002933e38086662a3f4b59aaed56c69021078c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 11:42:46 +0200
Subject: [PATCH 06/17] Add more endpoints

---
 docs/reference/swagger.yaml | 137 ++++++++++++++++++++++++++++++++++--
 1 file changed, 133 insertions(+), 4 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 57a27909..b228cdb9 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -317,9 +317,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/NamedMapResponseList'
+                $ref: '#/components/schemas/NamedMapResponseList'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -331,6 +329,131 @@ paths:
         - lang: Curl
           source: |
             curl -X GET 'https://{username}.carto.com/api/v1/map/named?api_key={api_key}'
+  '/map/named/{template_name}':
+    get:
+      summary: Get template definition
+      description: Get the definition of a requested template
+      tags:
+        - Named Maps
+      parameters:
+        - $ref: '#/components/parameters/templateName'
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Template'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyQueryParam: []
+        - ApiKeyHTTPBasicAuth: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X GET 'https://{username}.carto.com/api/v1/map/named/{template_name}?api_key={api_key}'
+    put:
+      summary: Update template definition
+      description: Update the definition of the template
+      tags:
+        - Named Maps
+      parameters:
+        - $ref: '#/components/parameters/templateName'
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NamedMapResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyQueryParam: []
+        - ApiKeyHTTPBasicAuth: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X PUT \
+              -H 'Content-Type: application/json' \
+              -d '{ \
+                "version": "0.0.1", \
+                "name": "template_name", \
+                "auth": { \
+                  "method": "token", \
+                  "valid_tokens": [ \
+                    "auth_token1", \
+                    "auth_token2" \
+                  ] \
+                }, \
+                "placeholders": { \
+                  "color": { \
+                    "type": "css_color", \
+                    "default": "red" \
+                  }, \
+                  "cartodb_id": { \
+                    "type": "number", \
+                    "default": 1 \
+                  } \
+                }, \
+                "layergroup": { \
+                  "version": "1.7.0", \
+                  "layers": [ \
+                    { \
+                      "type": "cartodb", \
+                      "options": { \
+                        "cartocss_version": "2.3.0", \
+                        "cartocss": "#layer { polygon-fill: <%= color %>; }", \
+                        "sql": "select * from european_countries_e WHERE cartodb_id = <%= cartodb_id %>" \
+                      } \
+                    } \
+                  ] \
+                }, \
+                "view": { \
+                  "zoom": 4, \
+                  "center": { \
+                    "lng": 0, \
+                    "lat": 0 \
+                  }, \
+                  "bounds": { \
+                    "west": -45, \
+                    "south": -45, \
+                    "east": 45, \
+                    "north": 45 \
+                  }, \
+                  "preview_layers": { \
+                    "0": true, \
+                    "layer1": false \
+                  } \
+                } \
+              }' \
+              'https://{username}.carto.com/api/v1/map/named/{template_name}?api_key={api_key}'
+    delete:
+      summary: Delete template
+      description: Deletes the specified template map from the server, and disables any previously initialized versions of the map.
+      tags:
+        - Named Maps
+      parameters:
+        - $ref: '#/components/parameters/templateName'
+      responses:
+        '204':
+          description: No Content
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyQueryParam: []
+        - ApiKeyHTTPBasicAuth: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X DELETE 'https://{username}.carto.com/api/v1/map/named/{template_name}?api_key={api_key}'
   '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}':
     get:
       parameters:
@@ -1100,7 +1223,6 @@ components:
       schema:
         type: string
       description: The named map name
-
     layersFilter:
       in: path
       name: layers_filter
@@ -1130,6 +1252,13 @@ components:
         title: layer index
         minimum: 0
       description: 0 based layer index
+    templateName:
+      in: path
+      name: template_name
+      required: true
+      schema:
+        type: string
+      description: Name of the requested template
   responses:
     NotFound:
       description: The specified resource was not found

From 380dab14612810a3a0c40f57789e189f0d81f2a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 12:46:00 +0200
Subject: [PATCH 07/17] Add title to components

---
 docs/reference/swagger.yaml | 71 +++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index b228cdb9..e58b8367 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -454,6 +454,56 @@ paths:
         - lang: Curl
           source: |
             curl -X DELETE 'https://{username}.carto.com/api/v1/map/named/{template_name}?api_key={api_key}'
+    post:
+      summary: Instantiate a Named Map
+      description: Instantiating a Named Map allows you to fetch the map tiles. You can use the Maps API to instantiate, or use the CARTO.js createLayer() function. The result is an Anonymous Map
+      tags:
+        - Named Maps
+      parameters:
+        - in: query
+          name: auth_token
+          description: >
+            `"token"` or `"open"` ("open" is the default if not specified. Use "token" to password-protect your map)
+          schema:
+            type: string
+      operationId: instantiateNamedMap
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TemplateParams'
+            example:
+              color: '#ff0000'
+              cartodb_id: 3
+      responses:
+        '200':
+          description: Ok. You can then use the layergroupid for fetching tiles and grids as you would normally
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemplateInstantiationResponse'
+              example:
+                layergroupid: 'docs@fd2861af@c01a54877c62831bb51720263f91fb33:123456788'
+                last_updated: '2013-11-14T11:20:15.000Z'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      security:
+        - ApiKeyQueryParam: []
+        - ApiKeyHTTPBasicAuth: []
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X POST \
+              -H 'Content-Type: application/json' \
+              -d '{ \
+                "color": "#ff0000", \
+                "cartodb_id": 3 \
+              }' \
+              'https://{username}.carto.com/api/v1/map/named/{template_name}?auth_token={auth_token}'
+  '/map/named/{template_name}/jsonp':
   '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}':
     get:
       parameters:
@@ -982,6 +1032,7 @@ components:
               type: string
     Template:
       type: object
+      title: Template
       properties:
         version:
           type: string
@@ -1012,8 +1063,12 @@ components:
         - auth
         - placeholders
         - layergroup
+    TemplateParams:
+      type: object
+      title: Template Parameters
     TemplatePlaceholders:
       type: object
+      title: Template Placeholders
       description: >
         Variables that can be placed in layergroup's definition (SQL or CartoCSS of any layer). Placeholders need to be defined with a `type` and a default value for MapConfigs. See details about defining a MapConfig `type` for [Layergroup configurations](http://docs.carto.com/carto-engine/maps-api/mapconfig/#layergroup-configurations). Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced inside the Named Maps API.
 
@@ -1036,6 +1091,7 @@ components:
         - default
     TemplateView:
       type: object
+      title: Template View
       description: Extra keys to specify the view area for the map. It can be used to have a static preview of a Named Map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box. Also it is possible to choose which layers are visible or not with `preview_layers` indicating its visibility by layer index or id (visible by default).
       properties:
         zoom:
@@ -1052,10 +1108,12 @@ components:
         - bounds
     TemplateViewZoom:
       type: number
+      title: Template View Zoom
       description: The zoom level to use
       example: 4
     TemplateViewCenter:
       type: object
+      title: Template View Center
       properties:
         lng:
           type: number
@@ -1068,6 +1126,7 @@ components:
         lat: 0
     TemplateViewBounds:
       type: object
+      title: Template View Bounds
       description: View area for the map. It can be used to have a static preview with bounding box `bbox
       properties:
         west:
@@ -1089,23 +1148,35 @@ components:
         north: 45
     TemplateViewPreviewLayers:
       type: object
+      title: Template View Preview Layers
       description: Indicates which layers are visible or not by layer index or id (visible by default).
       example:
         0: true
         layer1: false
     NamedMapResponse:
       type: object
+      title: Named Map Response
       properties:
         template_id:
           type: string
     NamedMapResponseList:
       type: object
+      title: Named Map Response List
       properties:
         template_ids:
           type: array
           items:
             type: string
             description: template name
+    TemplateInstantiationResponse:
+      type: object
+      title: Template Instantiation Response
+      poperties:
+        layergroupid:
+          type: string
+        last_updated:
+          type: string
+          format: date-time
   securitySchemes:
     ApiKeyHTTPBasicAuth:
       type: http

From 7c13561a4f7373504efc3bd7e0d5ff9ea94b107b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 13:28:53 +0200
Subject: [PATCH 08/17] Add jsonp named map instantiation endpoint

---
 docs/reference/swagger.yaml | 57 +++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 22 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index e58b8367..b2ee06d9 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -74,7 +74,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AnonymousMapResponse'
+                $ref: '#/components/schemas/MapResponse'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -482,17 +482,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/TemplateInstantiationResponse'
-              example:
-                layergroupid: 'docs@fd2861af@c01a54877c62831bb51720263f91fb33:123456788'
-                last_updated: '2013-11-14T11:20:15.000Z'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-      security:
-        - ApiKeyQueryParam: []
-        - ApiKeyHTTPBasicAuth: []
+                $ref: '#/components/schemas/MapResponse'
       x-code-samples:
         - lang: Curl
           source: |
@@ -504,6 +494,38 @@ paths:
               }' \
               'https://{username}.carto.com/api/v1/map/named/{template_name}?auth_token={auth_token}'
   '/map/named/{template_name}/jsonp':
+    get:
+      summary: Instantiate a Named Map using JSONP
+      description: Instantiating a Named Map allows you to fetch the map tiles. The result is an Anonymous Map
+      tags:
+        - Named Maps
+      parameters:
+        - $ref: '#/components/parameters/templateName'
+        - in: query
+          name: auth_token
+          description: >
+            `"token"` or `"open"` ("open" is the default if not specified. Use "token" to password-protect your map)
+          schema:
+            type: string
+        - in: query
+          name: config
+          description: >
+            Encoded JSON with the params (variables) needed for the Named Map
+          schema:
+            type: string
+        - in: query
+          name: callback
+          description: >
+            JSON callback name
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Ok. You can then use the layergroupid for fetching tiles and grids as you would normally
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MapResponse'
   '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}':
     get:
       parameters:
@@ -1003,7 +1025,7 @@ components:
         * **http** - load tiles over HTTP
         * **plain** - color or background image url
         * **named** - use a Named Map as a layer
-    AnonymousMapResponse:
+    MapResponse:
       type: object
       properties:
         layergroupid:
@@ -1168,15 +1190,6 @@ components:
           items:
             type: string
             description: template name
-    TemplateInstantiationResponse:
-      type: object
-      title: Template Instantiation Response
-      poperties:
-        layergroupid:
-          type: string
-        last_updated:
-          type: string
-          format: date-time
   securitySchemes:
     ApiKeyHTTPBasicAuth:
       type: http

From 44c4b29ea23edda3f84262d0717c0ed65034d026 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 15:11:08 +0200
Subject: [PATCH 09/17] Adding curl example

---
 docs/reference/swagger.yaml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index b2ee06d9..1eacaf5d 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -460,6 +460,7 @@ paths:
       tags:
         - Named Maps
       parameters:
+        - $ref: '#/components/parameters/templateName'
         - in: query
           name: auth_token
           description: >
@@ -526,6 +527,11 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MapResponse'
+      x-code-samples:
+        - lang: Curl
+          source: |
+            curl -X GET \
+            'https://{username}.carto.com/api/v1/map/named/{template_name}/jsonp?auth_token={auth_token}&callback=callback&config={"color":  "#ff0000", "cartodb_id": 3}'
   '/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}':
     get:
       parameters:

From 158f2159b77f929190197da316f352b7c74dcfdc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 17:37:46 +0200
Subject: [PATCH 10/17] Add layer query params

---
 docs/reference/swagger.yaml | 40 +++++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 1eacaf5d..b57be805 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -40,7 +40,8 @@ tags:
     externalDocs:
       url: 'https://carto.com/developers/maps-api/guides/named-maps/'
   - name: Static Maps
-    description: Create static images of parts of maps and thumbnails for use in web design, graphic design, print, field work, and many other applications that require standard image formats.
+    description: >
+      Create static images of parts of maps and thumbnails for use in web design, graphic design, print, field work, and many other applications that require standard image formats. Begin by instantiating either a Named or Anonymous Map using the layergroupid token to generate static images.
     externalDocs:
       url: 'https://carto.com/developers/maps-api/guides/static-maps-API/'
 paths:
@@ -542,9 +543,10 @@ paths:
         - $ref: '#/components/parameters/width'
         - $ref: '#/components/parameters/height'
         - $ref: '#/components/parameters/format'
+        - $ref: '#/components/parameters/layersQueryParam'
       summary: Zoom + center
       description: |
-        Zoom + center
+        Get static image by defining both the zoom level and geographic center (longitude & latitude)
       tags:
         - Static Maps
       operationId: getStaticZoomCenter
@@ -569,9 +571,7 @@ paths:
         - lang: Curl
           source: >
             curl -X GET \
-
-            https://username.carto.com/api/v1/map/static/center/c01a54877c62831bb51720263f91fb33/4/20/40/500/500.png
-
+            https://{username}.carto.com/api/v1/map/static/center/{layergroupid}/{z}/{lat}/{lng}/{width}/{height}.{format}?layer=all
   '/map/static/bbox/{layergroupid}/{west},{south},{east},{north}/{width}/{height}.{format}':
     get:
       parameters:
@@ -583,9 +583,10 @@ paths:
         - $ref: '#/components/parameters/width'
         - $ref: '#/components/parameters/height'
         - $ref: '#/components/parameters/format'
+        - $ref: '#/components/parameters/layersQueryParam'
       summary: Bounding Box
       description: |
-        Bounding Box in WGS 84 (EPSG:4326), comma separated values
+        Get static image by defining bounding box in WGS 84 (EPSG:4326), comma separated values
       tags:
         - Static Maps
       operationId: getStaticBoundingBox
@@ -611,7 +612,7 @@ paths:
           source: >
             curl -X GET \
 
-            https://username.carto.com/api/map/static/bbox/c01a54877c62831bb51720263f91fb33/0/0/30/30/500/500.png
+            https://{username}.carto.com/api/map/static/bbox/{layergroupid}/{west},{south},{east},{north}/{width}/{height}.{format}?layer=all
   '/map/static/named/{name}/{width}/{height}.{format}':
     get:
       parameters:
@@ -621,7 +622,7 @@ paths:
         - $ref: '#/components/parameters/format'
       summary: Named map
       description: |
-        Named map
+        Get the static image of a Named Map by defining width, height and, format. It will use the default vaules defined in the template
       tags:
         - Static Maps
       operationId: getStaticNamedMap
@@ -646,9 +647,7 @@ paths:
         - lang: Curl
           source: >
             curl -X GET \
-
-            https://username.carto.com/api/map/static/named/mynamedmap/500/500.png
-
+            https://{username}.carto.com/api/map/static/named/{name}/{width}/{height}.{format}
 components:
   schemas:
     MapConfig:
@@ -1333,6 +1332,25 @@ components:
           * **2** - only one layer
 
         * **all** will blend all layers in the layergroup
+    layersQueryParam:
+      in: query
+      name: layer
+      schema:
+        oneOf:
+          - type: string
+            title: all
+          - type: string
+            title: list of indexes
+      description: |
+        Layers to be rendered together.
+
+        Supports 2 format options:
+        * a comma separated list of layer indexes (0-based). Examples:
+
+          * **0,1,3** - will filter and blend layers with indexes 0, 1 and 3
+          * **2** - only one layer
+
+        * **all** will blend all layers in the layergroup (**default value**)
     layerIndex:
       in: path
       name: layer

From 7822f59fd4c02ae4bca119df8630736e03dc5d19 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 17:40:04 +0200
Subject: [PATCH 11/17] Typo

---
 docs/reference/swagger.yaml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index b57be805..3ed99417 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -611,7 +611,6 @@ paths:
         - lang: Curl
           source: >
             curl -X GET \
-
             https://{username}.carto.com/api/map/static/bbox/{layergroupid}/{west},{south},{east},{north}/{width}/{height}.{format}?layer=all
   '/map/static/named/{name}/{width}/{height}.{format}':
     get:

From 02dc61b7c74c89fe9bb7d69104f0a0b8c0474d5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 24 Aug 2018 18:04:16 +0200
Subject: [PATCH 12/17] Add Bad Request

---
 docs/reference/swagger.yaml | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 3ed99417..b4a5d604 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -245,6 +245,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/NamedMapResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -319,6 +321,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/NamedMapResponseList'
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -345,10 +349,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Template'
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -370,10 +378,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/NamedMapResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -444,10 +456,14 @@ paths:
       responses:
         '204':
           description: No Content
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -485,6 +501,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MapResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
       x-code-samples:
         - lang: Curl
           source: |
@@ -528,6 +548,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/MapResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
       x-code-samples:
         - lang: Curl
           source: |
@@ -558,6 +582,8 @@ paths:
               schema:
                 type: string
                 format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -598,6 +624,8 @@ paths:
               schema:
                 type: string
                 format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -633,6 +661,8 @@ paths:
               schema:
                 type: string
                 format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
@@ -1367,6 +1397,8 @@ components:
         type: string
       description: Name of the requested template
   responses:
+    BadRequest:
+      description: The server could not understand the request due to invalid syntax.
     NotFound:
       description: The specified resource was not found
     Unauthorized:

From 9de9c57dc2542f14a2b966ead96acd71509fceeb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Mon, 27 Aug 2018 11:55:52 +0200
Subject: [PATCH 13/17] Remove meaningless sentence

---
 docs/reference/swagger.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index b4a5d604..523fd4ce 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -473,7 +473,7 @@ paths:
             curl -X DELETE 'https://{username}.carto.com/api/v1/map/named/{template_name}?api_key={api_key}'
     post:
       summary: Instantiate a Named Map
-      description: Instantiating a Named Map allows you to fetch the map tiles. You can use the Maps API to instantiate, or use the CARTO.js createLayer() function. The result is an Anonymous Map
+      description: Instantiating a Named Map allows you to fetch the map tiles. The result is an Anonymous Map
       tags:
         - Named Maps
       parameters:

From 5b30c390fd20da203a05385d1b7741d4caf43256 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Mon, 27 Aug 2018 17:25:52 +0200
Subject: [PATCH 14/17] Add 500 server internal error

---
 docs/reference/swagger.yaml | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 523fd4ce..c763ea85 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -80,6 +80,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -117,6 +119,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -153,6 +157,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -189,6 +195,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -251,6 +259,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -327,6 +337,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -357,6 +369,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -386,6 +400,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -464,6 +480,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyQueryParam: []
         - ApiKeyHTTPBasicAuth: []
@@ -505,6 +523,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       x-code-samples:
         - lang: Curl
           source: |
@@ -552,6 +572,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       x-code-samples:
         - lang: Curl
           source: |
@@ -590,6 +612,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -632,6 +656,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -669,6 +695,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
       security:
         - ApiKeyHTTPBasicAuth: []
         - ApiKeyQueryParam: []
@@ -1397,8 +1425,10 @@ components:
         type: string
       description: Name of the requested template
   responses:
+    InternalServerError:
+      description: Server encountered an unexpected condition that prevented it from fulfilling the request.
     BadRequest:
-      description: The server could not understand the request due to invalid syntax.
+      description: The server could not understand the request due to invalid syntax or unexpected condition.
     NotFound:
       description: The specified resource was not found
     Unauthorized:

From 2ec0b4674ca42023e0159105f6025c79f8a1aa1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Mon, 27 Aug 2018 17:49:38 +0200
Subject: [PATCH 15/17] Add 429 too many request error

---
 docs/reference/swagger.yaml | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index c763ea85..85c06048 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -80,6 +80,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -119,6 +121,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -157,6 +161,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -195,6 +201,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -259,6 +267,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -337,6 +347,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -369,6 +381,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -400,6 +414,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -480,6 +496,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -523,6 +541,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       x-code-samples:
@@ -572,6 +592,8 @@ paths:
           $ref: '#/components/responses/BadRequest'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       x-code-samples:
@@ -612,6 +634,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -656,6 +680,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -695,6 +721,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequest'
         '500':
           $ref: '#/components/responses/InternalServerError'
       security:
@@ -1430,10 +1458,12 @@ components:
     BadRequest:
       description: The server could not understand the request due to invalid syntax or unexpected condition.
     NotFound:
-      description: The specified resource was not found
+      description: The specified resource was not found.
     Unauthorized:
       description: Unauthorized. No authentication provided.
     Forbidden:
       description: Forbidden. The API key does not authorize this request.
     BadInput:
-      description: Request's parameters error
+      description: Request's parameters error.
+    TooManyRequest:
+      description: The user has sent too many requests in a given amount of time ("rate limiting" or "database timeout").

From 94cd3d008c39971469515313e30731967b7d41dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Tue, 28 Aug 2018 09:37:16 +0200
Subject: [PATCH 16/17] Add placeholder default value

---
 docs/reference/swagger.yaml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index 85c06048..a9c898f4 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -1197,10 +1197,15 @@ components:
             number: can only contain numerical representation
             css_color: can only contain color names or hex-values
         default:
-          type: string
+          $ref: '#/components/schemas/PlaceholderDefaultValue'
       required:
         - type
         - default
+    PlaceholderDefaultValue:
+      anyOf:
+        - type: string
+        - type: number
+        - type: boolean
     TemplateView:
       type: object
       title: Template View

From 810ad46446a3483fe93b8beef659d8cb04a2429a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Tue, 28 Aug 2018 09:38:59 +0200
Subject: [PATCH 17/17] Simplify schemas

---
 docs/reference/swagger.yaml | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/docs/reference/swagger.yaml b/docs/reference/swagger.yaml
index a9c898f4..ccb84146 100644
--- a/docs/reference/swagger.yaml
+++ b/docs/reference/swagger.yaml
@@ -1197,15 +1197,13 @@ components:
             number: can only contain numerical representation
             css_color: can only contain color names or hex-values
         default:
-          $ref: '#/components/schemas/PlaceholderDefaultValue'
+          anyOf:
+            - type: string
+            - type: number
+            - type: boolean
       required:
         - type
         - default
-    PlaceholderDefaultValue:
-      anyOf:
-        - type: string
-        - type: number
-        - type: boolean
     TemplateView:
       type: object
       title: Template View