Windshaft-cartodb/docs/Template-maps.md

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 types

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@fd2861af@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"
}