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/Multilayer-API). The set of supported placeholders for a template will need to be explicitly defined. 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"
   valid_tokens: ['auth_token1','auth_token2']
  },
  // Variables not listed here are not substituted
  // Required variable not provided at instantiation time trigger an error
  // A default is required for optional variables
  // Specifying a type serves the purpose of proper quoting, to avoid injections
  placeholders: {
      color: { type:'css_color', default:'red' }, // required:false by default
      cartodb_id: { type:'number', required:true, default: 1 } // default still required for map validation
  },
  layergroup: { // see https://github.com/CartoDB/Windshaft/wiki/Multilayer-API
   "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 %>"
    }
   }]
  } 
}

TODO: list valid placeholder types

Creating a templated map

You should be able to create a signed template map with a single call (for simplicity). You'd use a POST:

curl 'https://docs.cartodb.com/tiles/layergroup/template?api_key=APIKEY' -d @template.json

The response would be like this:

{
   "template_id":"@template_name"
}

When using POST, if a template with the same name exists in the user storage, an error will be raised. You can use PUT for update, which would error out if the named template does NOT exist.

Listing available templates

You can get a list of available templates with a GET to /layergroup/templates (NOTE the final 's'):

curl 'https://docs.cartodb.com/tiles/layergroup/templates?api_key=APIKEY'

The response would be like this:

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

Getting a specific template

You can get the definition of a template with a GET to /layergroup/template/<template_name>:

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

NOTE: I don't like using the same URL as the one used to instantiate

The response would be like this:

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

Instantiating a template map

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

curl -d '' 'https://docs.cartodb.com/tiles/layergroup/template/@template_name?auth_token=AUTH_TOKEN&param1=value1&param2=value2'

The response would be like this:

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

You can then use the layergroup_id for fetching tiles and grids, 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. VERIFY

Deleting a template map

Deletion of a template map should imply removal all instance signatures

Updating a template map

Update of a template map should imply removal all instance signatures