Multilayer API

This document describes the proposed future API to manage and use windshaft layers. The aim is to reduce the duplication of configuration among the multiple tiles and grids requests and at the same time to use a short url to fetch those subproduct of a "configured layer group".

Intro

The proposed API allows to create a new endpoint in the tiler which allow to retrieve tiles and interactivity grid for a group of layers defined by a SQL and a CartoCSS (among other options)

layergroup api interface

• create a new layergroup should be a POST (we should define the way it should do for clients which do not support CORS) to /layergroup with the layergroup definition in the body (content-type application/json).

  {
  

version: '1.0.1', extent: "-180,-90,180,90", //optional (possibly needed to fetch a tile for test purposes) maxzoom: 18, //optional (what for?) minzoom:3, //optional (what for?) global_cartocss:'#layer0{} #layer1{}...', // optional, takes precedence over per-layer setting global_cartocss_version: '2.0.1', // optional, takes precedence over per-layer setting // layers are defined in order to the first will be rendered first layers: [ { type: 'cartodb', // Tiler doesn't need this, right ? Can't be anything else. Yes I dont think is needed. But we can use it to specify the resultformat of the tile (png64, png8, json, etc.) options: { sql: 'select * from whatever', affected_tables: [ 'table1', 'schema.table2', '"MixedCase"."Table"' ], /* optional / cartocss: '#layer { ... }', / global_cartocss takes precedence over this, if present / cartocss_version: '2.0.1', / global_cartocss_version takes precedence over this, if present */ interactivity: [ 'field1', ... ] } }, { // other layer definition } ] } ```

The tiler will create a temporary mapnik configuration, assign it a token, try its validity (try to fetch a tile and a grid) and return the token. The same configuration will result in the same token. The client can use this token to fetch tiles or grids. There is no guarantee that the token remains alive so the client should be ready to catch 404 errors when accessing tiles.

The response will contain a timestamp corresponding to the most recent change in the data of any of the tables involved in any layer.

The response should be like this:

   {
      layergroupid: 'TOKEN',
      last_updated: '1358957974', // EPOCH -- Proposed for REMOVAL by strk on 2013-04-05
      errors: [
          // sql errors (syntax errors)
          // cartodcss errors (syntax)
          // runtime errors (no permissions for the tables or the tiles can't be rendered)
      ]
      
   }

• fetch tiles from it

  /layergroup/:TOKEN/:Z/:X/:Y.png

• fetch grids from it

  /layergroup/:TOKEN/:LAYER/:Z/:X/:Y.grid.json

grid.json tiles will contain the interactivity specified in the configuration for the given layer. Layers are referenced by index (0..N). If no interactivity was specified for the given layer an error will be returned.

tiler internals

layergroups storage

they are temporary and stored within redis under grainstore responsibility

cache management

they expire after some configured number of seconds since last access

table schema needed

we need to define a model to know the "last_updated" timestamp for the data

public private considerations

security will be left to postgresql layer and checked at get tile time