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', ... ] / highest layer with this set will be used for grids */ } }, { // 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: '123123123123',
      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/:Z/:X/:Y.grid.json

grid.json tiles will contain the interactivity of the uppermost layers in the configuration.
If you need multiple grids you can use multiple configurations/tokens.

 # 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