Tango REST API v1.0

There are three parts in this proposal: URL specification; Implementation remarks; Implementation recommendations. The first one names valid URLs that must be handled by the implementation. Each URL is presented following this format:

URL RESPONSE TYPE NOTE
METHOD url JSONArray/JSONObject/NULL short comment

Such table is followed by a JSON response's examples block:

URL: {'JSON response':'example'}

In two following sections several implementation guidelines are highlighted.

In general API follows standard CRUD idiom:

HTTP verb CRUD collection instance
GET READ Read a list. 200 OK Read the details of one instance. 200 OK
POST CREATE Create a new instance. 201 OK -
PUT UPDATE/CREATE Full Update. 200 OK Create an instance. 201 Created
DELETE DELETE - Delete instance. 200 OK

POST create an instance of collection by the URI of this collection. POST returns the URI and the id of the newly created instance.

URL example driven specification

All URLs in this section omit protocol//host:port part: http://host:port. An implementation may or may not add this to the hrefs.

For shortness all URLs use <prefix> for an API entry point: /tango/rest/v1.0, or omit it completely. If not specified otherwise <prefix> includes hosts/localhost as well i.e. /tango/rest/v1.0/hosts/localhost. So <prefix>/hosts/localhost/devices/sys/tg_test/1/attributes (or <prefix>/devices/sys/tg_test/1/attributes or /devices/sys/tg_test/1/attributes) actually means /tango/rest/v1.0/hosts/localhost/devices/sys/tg_test/1/attributes.

Examples are typically follow this pattern:

METHOD url[?params]

Request body
Response body

Examples may be supplied with headers if required. Headers pretend body block:

METHOD url[?params]

Request headers

Request body
Response headers

Response body

Implementation remarks

  1. Implement async where possible (almost any PUT, POST and DELETE methods)
  2. All constants and magic numbers in responses, i.e. data type, data format, writable, level must be replaced with their string representation
  3. Image attributes must be handled on the server side, i.e. server safes image as jpeg (or tiff) and sends URL or embeds this image into response.
  4. API must be allowed only for authorized users.
  5. Optionally provide integration with TangoAccessControl
  6. Optional shortcuts may be implemented to reduce data transfer
  7. Provide access to set_attribute_config() via admin panel
  8. PUT attribute can be implemented as write_read call.

Implementation recommendations

  1. Implementation must cache Tango proxy objects
  2. Implementation must provide Expires response header value related requests (attribute value read)
  3. Implementation must export configuration for all caches, i.e. how long keep read value

References

[1] Brian Mulloy, Web API Design. Crafting Interfaces that Developers Love