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.

  {
  

version: '1.0.0', 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: 'cartodb_id, whatever, columns' / comma separated columns to be included in the interactivity layer */ } }, { // other layer definition

} ], } ```

The tiler will create a temporary mapnik configuration, assign it a token, try its validity (try to fetch a tile) and return the token. The same configuration will result in the same token. The client can use this token to fetch tiles. 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: '123123123123', // could be added by Windahsft-CartoDB, not Windshaft core
      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, grid.json]

grid.json tiles will contain the interactivity for the layers selected. In the first version only one layer will be accepted so if more than one layer has interactivity the layer creation could raise an error or take only the lastest

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