Include API docs, moved from wiki

Closes #164
2014-03-04 15:39:21 +01:00
parent ffda103d61
commit 033f8df500
4 changed files with 419 additions and 0 deletions
@@ -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:

@@ -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 }
+
@@ -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.
@@ -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"
+}
+```