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:
Such table is followed by a JSON response's examples block:
In two following sections several implementation guidelines are highlighted.
In general API follows standard CRUD idiom:
|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
hosts/localhost as well i.e.
/devices/sys/tg_test/1/attributes) actually means
Examples are typically follow this pattern:
Examples may be supplied with headers if required. Headers pretend body block:
Request headers Request body
Response headers Response body
- Implement async where possible (almost any PUT, POST and DELETE methods)
- All constants and magic numbers in responses, i.e. data type, data format, writable, level must be replaced with their string representation
- 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.
- API must be allowed only for authorized users.
- Optionally provide integration with TangoAccessControl
- Optional shortcuts may be implemented to reduce data transfer
- Provide access to set_attribute_config() via admin panel
- PUT attribute can be implemented as write_read call.
- Implementation must cache Tango proxy objects
- Implementation must provide Expires response header value related requests (attribute value read)
- Implementation must export configuration for all caches, i.e. how long keep read value