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 -X POST 'https://docs.cartodb.com/tiles/template?api_key=APIKEY' -d @template.json

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 should be able to update a signed template map with a single call (for simplicity). You'd use a PUT:

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

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:

curl -X POST 'https://docs.cartodb.com/tiles/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"
}

or, on error:

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

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 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'

The response would be like this:

{
   "status":"ok"
}

or, on error:

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