Template maps

Template maps are layergroup configurations that rather than being fully defined contain variables that can be set to produce a different layergroup configurations (instantiation).

Template maps are persistent, can only be created and deleted by the CartoDB user showing a valid API_KEY.

Instantiating a signed template map would result in a signed map instance that would be signed with the same signature as the template.

Deleting a signed template results in deletion of all signatures created as a result of instantiation.

Template format

A templated layergroup would allow using placeholders in the "cartocss" and "sql" elements in the "option" field of any "layer" of a layergroup configuration (see https://github.com/CartoDB/Windshaft/wiki/MapConfig-specification).

Valid placeholder names start with a letter and can only contain letters, numbers or underscores. They have to be written between <%= and %> strings in order to be replaced. Example: <%= my_color %>.

The set of supported placeholders for a template will need to be explicitly defined specifying type and default value for each.

Placeholder type will determine the kind of escaping for the associated value. Supported types are:

• 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)
• ... (add more as need arises)

Placeholder default value will be used when not provided at instantiation time and could be used to test validity of the template by creating a default instance.

Additionally you'll be able to embed an authorization certificate that would be used to sign any instance of the template.

// template.json 
{
  version: '0.0.1',
  // there can be at most 1 template with the same name for any user 
  // valid names start with a letter and only contains letter, numbers
  // or underscores
  name: 'template_name', 
  // embedded authorization certificate
  auth: {
   // See https://github.com/CartoDB/Windshaft-cartodb/wiki/Signed-maps
   method: 'token', // or "open" (the default if no "method" is given)
   valid_tokens: ['auth_token1','auth_token2'] // only (required and non empty) for 'token' method
  },
  // Variables not listed here are not substituted
  // Variable not provided at instantiation time trigger an error
  // A default is required for optional variables
  // Type specification is used for quoting, to avoid injections
  placeholders: {
      color: {
        type:'css_color',
        default:'red'
      },
      cartodb_id: {
        type:'number',
        default: 1
      }
  },
  layergroup: {
   // see https://github.com/CartoDB/Windshaft/wiki/MapConfig-specification
   "version": "1.0.1",
   "layers": [{
    "type": "cartodb",
    "options": {
      "cartocss_version": "2.1.1", 
      "cartocss": "#layer { polygon-fill: <%= color %>; }",
      "sql": "select * from european_countries_e WHERE cartodb_id = <%= cartodb_id %>"
    }
   }]
  } 
}

Creating a templated map

You can create a signed template map with a single call (for simplicity). You'd use a POST sending JSON data:

curl -X POST \
   -H 'Content-Type: application/json' \
   -d @template.json \
   'https://docs.cartodb.com/tiles/template?api_key=APIKEY'

The response would be like this:

{
   "template_id":"@template_name"
}

If a template with the same name exists in the user storage, a 400 response is generated.

Errors are in this form:

{
   "error":"Some error string here"
}

Updating an existing template

Update of a template map implies removal all signatures from previous map instances.

You can update a signed template map with a PUT:

curl -X PUT \
   -H 'Content-Type: application/json' \
   -d @template.json \
   'https://docs.cartodb.com/tiles/template/:template_name?api_key=APIKEY'

A template with the same name will be updated, if any.

The response would be like this:

{
   "template_id":"@template_name"
}

If a template with the same name does NOT exist, a 400 HTTP response is generated with an error in this format:

{
   "error":"Some error string here"
}

Listing available templates

You can get a list of available templates with a GET to /template. A valid api_key is required.

curl -X GET 'https://docs.cartodb.com/tiles/template?api_key=APIKEY'

The response would be like this:

{
   "template_ids": ["@template_name1","@template_name2"]
}

Or, on error:

{
   "error":"Some error string here"
}

Getting a specific template

You can get the definition of a template with a GET to /template/:template_name. A valid api_key is required.

Example:

curl -X GET 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN'

The response would be like this:

{
   "template": {...}  // see template.json above
}

Or, on error:

{
   "error":"Some error string here"
}

Instantiating a template map

You can instantiate a template map passing all required parameters with a POST to /template/:template_name.

Valid credentials will be needed, if required by the template.

// params.js
{
 color: '#ff0000',
 cartodb_id: 3
}

curl -X POST \
  -H 'Content-Type: application/json' \
  -d @params.js \
  'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN'

The response would be like this:

{
   "layergroupid":"docs@c01a54877c62831bb51720263f91fb33:123456788",
   "last_updated":"2013-11-14T11:20:15.000Z"
}

or, on error:

{
   "error":"Some error string here"
}

You can then use the layergroupid for fetching tiles and grids as you do normally ( see https://github.com/CartoDB/Windshaft/wiki/Multilayer-API). But you'll still have to show the auth_token, if required by the template (see https://github.com/CartoDB/Windshaft-cartodb/wiki/Signed-maps)

Instances of a signed template map will be signed with the same signature certificate associated with the template. Such certificate would contain a reference to the template identifier, so that it can be revoked every time the template is updated or deleted.

using JSONP

There is also a special endpoint to be able to instanciate using JSONP (for old browsers)

curl 'https://docs.cartodb.com/tiles/template/@template_name/jsonp?auth_token=AUTH_TOKEN&callback=function_name&config=template_params_json'

it takes the callback function (required), auth_token in case the template needs auth and config which is the variabñes for the template (in case it has variables). For example config may be created (using javascript)

url += "config=" + encodeURIComponent(
JSON.stringify({ color: 'red' });

the response it's in this format:

jQuery17205720721024554223_1390996319118(
{
layergroupid: "dev@744bd0ed9b047f953fae673d56a47b4d:1390844463021.1401",
last_updated: "2014-01-27T17:41:03.021Z"
}
)

Deleting a template map

Deletion of a template map will imply removal all instance signatures

You can delete a templated map with a DELETE to /template/:template_name:

curl -X DELETE 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN'

On success, a 204 (No Content) response would be issued. Otherwise a 4xx response with this format:

{
   "error":"Some error string here"
}