From 033f8df500a3d4774f1c349579162aabe070ce79 Mon Sep 17 00:00:00 2001 From: Sandro Santilli Date: Tue, 4 Mar 2014 15:39:21 +0100 Subject: [PATCH] Include API docs, moved from wiki Closes #164 --- NEWS.md | 1 + docs/Map-API.md | 111 ++++++++++++++++ docs/MultiLayer-API.md | 15 +++ docs/Template-maps.md | 292 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 419 insertions(+) create mode 100644 docs/Map-API.md create mode 100644 docs/MultiLayer-API.md create mode 100644 docs/Template-maps.md diff --git a/NEWS.md b/NEWS.md index 1a2534a0..531953e1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -8,6 +8,7 @@ Enhancements: signature of someone who had not left any (#170) - Do not log an error on GET / (#177) - Do not UNWATCH on every redis client release (#161) + - Include API docs (#164) Bug fixes: diff --git a/docs/Map-API.md b/docs/Map-API.md new file mode 100644 index 00000000..0956f271 --- /dev/null +++ b/docs/Map-API.md @@ -0,0 +1,111 @@ +# Kind of maps + +Windshaft-CartoDB supports these kind of maps: + + - [Temporary maps](#temporary-maps) (created by anyone) + - [Detached maps](#detached-maps) + - [Inline maps](#inline-maps) (legacy) + - [Persistent maps](#peristent-maps) (created by CartDB user) + - [Template maps](#template-maps) + - [Table maps](#table-maps) (legacy, deprecated) + +## Temporary maps + +Temporary maps have no owners and are anonymous in nature. +There are two kind of temporary maps: + + - Detached maps (aka MultiLayer-API) + - Inline maps + +### Detached maps + +Detached maps are maps which are configured with a request +obtaining a temporary token and then used by referencing +the obtained token. The token expires automatically when unused. + +Anyone can create detached maps, but users will need read access +to the data source of the map layers. + +The configuration format is a [MapConfig] +(http://github.com/CartoDB/Windshaft/wiki/MapConfig-specification) document. + +The HTTP endpoints for creating the map and using it are described [here] +(http://github.com/CartoDB/Windshaft-cartodb/wiki/MultiLayer-API) + +*TODO* cleanup the referenced document + +### Inline maps + +Inline maps are maps that only exist for a single request, +being the request for a specific map resource (tile). + +Inline maps are always bound to a table, and can only be +obtained by those having read access to the that table. +Additionally, users need to have access to any datasource +specified as part of the configuration. + +Inline maps only support PNG and UTF8GRID tiles. + +The configuration consist in a set of parameters, to be +specified in the query string of the tile request: + + * sql - the query to run as datasource, can be an array + * style - the CartoCSS style for the datasource, can be an array + * style_version - version of the CartoCSS style, can be an array + * interactivity - only for fetching UTF8GRID, + +If the style is not provided, style of the associated table is +used; if the sql is not provided, all records of the associated +table are used as the datasource; the two possibilities result +in a mix between _inline_ maps and [Table maps][]. + +*TODO* specify (or link) api endpoints + +## Persistent maps + +Persistent maps can only be created by a CartoDB user who has full +responsibility over editing and deleting them. There are two +kind of persistent maps: + + - Template maps + - Table maps (legacy, deprecated) + +### Templated maps + +Templated maps are templated [MapConfig] +(http://github.com/CartoDB/Windshaft/wiki/MapConfig-specification) documents +associated with an authorization certificate. + +The authorization certificate determines who can instanciate the +template and use the resulting map. Authorized users of the instanciated +maps will have the same database access privilege of the template owner. + +The HTTP endpoints for creating and using templated maps are described [here] +(http://github.com/CartoDB/Windshaft-cartodb/wiki/Template-maps). + +*TODO* cleanup the referenced document + +### Table maps + +Table maps are maps associated with a table. +Configuration of such maps is limited to the CartoCSS style. + + * style - the CartoCSS style for the datasource, can be an array + * style_version - version of the CartoCSS style, can be an array + +You can only fetch PNG or UTF8GRID tiles from these maps. + +Access method is the same as the one for [Inline maps](#inline-maps) + +# Endpoints description + +- **/api/maps/** (same interface than https://github.com/CartoDB/Windshaft/wiki/Multilayer-API) +- **/api/maps/named** (same interface than https://github.com/CartoDB/Windshaft-cartodb/wiki/Template-maps) + + +NOTE: in case Multilayer-API does not contain this info yet, the + endpoint for fetching attributes is this: + +- **/api/maps/:map_id/:layer_index/attributes/:feature_id** + - would return { c: 1, d: 2 } + diff --git a/docs/MultiLayer-API.md b/docs/MultiLayer-API.md new file mode 100644 index 00000000..d8829db8 --- /dev/null +++ b/docs/MultiLayer-API.md @@ -0,0 +1,15 @@ +The Windshaft-CartoDB MultiLayer API extends the [Windshaft MultiLayer API](https://github.com/Vizzuality/Windshaft/wiki/Multilayer-API) in a few ways. + +## Last modification timestamps + +It encodes a timestamp of 'last modification time' into the map token (token:EPOCH) returned to the client. +It accepts tokens with encoded timestamp from the client considering the token suffix as a cache_buster value. + +Clients don't need to be aware of the extension but rather use the API as they would use the base one. +The only difference will be that the _same_ layergroup configuration may result in different tokens if source data was modified between the mapview requests. + +Also Windshaft-CartoDB adds a ``last_update`` field with ISO format (2013-11-30T12:23:10). + +## Stats tag + +Windshaft-CartoDB adds support for a ``stat_tag`` element in the multilayer configuration to help [stats](Redis-stats-format) gathering. \ No newline at end of file diff --git a/docs/Template-maps.md b/docs/Template-maps.md new file mode 100644 index 00000000..e7faf7f0 --- /dev/null +++ b/docs/Template-maps.md @@ -0,0 +1,292 @@ +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](https://github.com/CartoDB/Windshaft-cartodb/wiki/Signed-maps) +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/MapConfig-specification). + +Valid placeholder names start with a letter and can only +contain letters, numbers or underscores. They have to be +written between ``<%= `` and `` %>`` strings in order to be +replaced. Example: ``<%= my_color %>``. + +The set of supported placeholders for a template will need to be +explicitly defined specifying type and default value for each. + +**placeholder types** + +Placeholder type will determine the kind of escaping for the +associated value. Supported types are: + + * sql_literal (internal single-quotes will be sql-escaped) + * sql_ident (internal double-quotes will be sql-escaped) + * number (can only contain numerical representation) + * css_color (can only contain color names or hex-values) + * ... (add more as need arises) + +Placeholder default value will be used when not provided at +instantiation time and could be used to test validity of the +template by creating a default instance. + +Additionally you'll be able to embed an authorization +certificate that would be used to sign any instance of the template. + +```js +// 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" (the default if no "method" is given) + valid_tokens: ['auth_token1','auth_token2'] // only (required and non empty) for 'token' method + }, + // Variables not listed here are not substituted + // Variable not provided at instantiation time trigger an error + // A default is required for optional variables + // Type specification is used for quoting, to avoid injections + placeholders: { + color: { + type:'css_color', + default:'red' + }, + cartodb_id: { + type:'number', + default: 1 + } + }, + layergroup: { + // see https://github.com/CartoDB/Windshaft/wiki/MapConfig-specification + "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 %>" + } + }] + } +} +``` + +# Creating a templated map + +You can create a signed template map with a single call (for simplicity). +You'd use a POST sending JSON data: + +```sh +curl -X POST \ + -H 'Content-Type: application/json' \ + -d @template.json \ + 'https://docs.cartodb.com/tiles/template?api_key=APIKEY' +``` + +The response would be like this: +```js +{ + "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: +```js +{ + "error":"Some error string here" +} +``` + +# Updating an existing template + +Update of a template map implies removal all signatures from previous +map instances. + +You can update a signed template map with a PUT: + +```sh +curl -X PUT \ + -H 'Content-Type: application/json' \ + -d @template.json \ + 'https://docs.cartodb.com/tiles/template/:template_name?api_key=APIKEY' +``` +A template with the same name will be updated, if any. + +The response would be like this: +```js +{ + "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: + +```js +{ + "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. + +```sh +curl -X GET 'https://docs.cartodb.com/tiles/template?api_key=APIKEY' +``` + +The response would be like this: +```js +{ + "template_ids": ["@template_name1","@template_name2"] +} +``` + +Or, on error: + +```js +{ + "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: + +```sh +curl -X GET 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN' +``` + +The response would be like this: +```js +{ + "template": {...} // see template.json above +} +``` + +Or, on error: + +```js +{ + "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``. + +Valid credentials will be needed, if required by the template. + +```js +// params.js +{ + color: '#ff0000', + cartodb_id: 3 +} +``` + +```sh +curl -X POST \ + -H 'Content-Type: application/json' \ + -d @params.js \ + 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN' + +``` + +The response would be like this: +```js +{ + "layergroupid":"docs@fd2861af@c01a54877c62831bb51720263f91fb33:123456788", + "last_updated":"2013-11-14T11:20:15.000Z" +} +``` + +or, on error: + +```js +{ + "error":"Some error string here" +} +``` + +You can then use the ``layergroupid`` for fetching tiles and grids as you do +normally ( see https://github.com/CartoDB/Windshaft/wiki/Multilayer-API). +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. + +### using JSONP +There is also a special endpoint to be able to instanciate using JSONP (for old browsers) + +``` +curl 'https://docs.cartodb.com/tiles/template/@template_name/jsonp?auth_token=AUTH_TOKEN&callback=function_name&config=template_params_json' +``` + +it takes the ``callback`` function (required), ``auth_token`` in case the template needs auth and ``config`` which is the variabñes for the template (in case it has variables). For example config may be created (using javascript) +``` +url += "config=" + encodeURIComponent( +JSON.stringify({ color: 'red' }); +``` + +the response it's in this format: +``` +jQuery17205720721024554223_1390996319118( +{ +layergroupid: "dev@744bd0ed9b047f953fae673d56a47b4d:1390844463021.1401", +last_updated: "2014-01-27T17:41:03.021Z" +} +) +``` +# 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``: + +```sh +curl -X DELETE 'https://docs.cartodb.com/tiles/template/@template_name?auth_token=AUTH_TOKEN' +``` + +On success, a 204 (No Content) response would be issued. +Otherwise a 4xx response with this format: + +```js +{ + "error":"Some error string here" +} +```