-
protocol definition
+protocol definition
by Dr. Patrick Bartsch 2013-2016
+by Dr. Patrick Bartsch 2013-2017
-
version: v 1.7.0-W3C
+version: v 1.8.0-W3C
-
- Introduction
+
+ Introduction
Purpose of this document
This document provides an overview over web services on the WebInfotainment platform. All services provide mainly HTTP_GET, HTTP_POST, HTTP_PUT, HTTP_DELETE (herein called GET, POST, PUT, DELETE) and WebSocket interfaces. The response is always of contentType: application/json (or application/vnd.viwi.v<major>.<minor>.<patch>+json for a dedicated version), this also applies for the WebSocket interface. The general approach is a RESTful API.
Purpose of this document
Paradigms
The API described herein follows some general 'design rules' or 'paradigms'. Deviation of actual interface definition must be minimized in a reasonable way.
-
-
-
-
The depth of the URI tree is limited to 3, i.e.
-/<service>/<resource>/<element>. While<service>and<resource>are predefined in this document,<element>will always be an identifier or the keyword 'spec'.<resource>is always a collection (e.g stations) and thus has to be a noun plural form, even if the<resource>will also carry a single<element>by design. The<resource>identifiers must not carry verbs likegetAccountorcreateTrack.
- -
-
An event is considered 'on change' if two subsequent GET requests on the corresponding URI would result in different responses (only the response objects own properties are relevant). If an elements property 'name' is changed, an 'on change' event is fired (Publish Subscribe). If an element is added or removed from a list of objects (on resource level), an 'on change' event is fired (Publish Subscribe). If a client wants to get notified on nested properties or structures, the corresponding event has to be subscribed individually.
-
- -
-
To keep the overall network traffic at a minimum, every resource and element access supports filtering. The response filtering concepts "fields", "paging" and "expand" are generally available.
-
- -
-
Every object inherits from XObject. I.e. every Object has three mandatory properties: id, uri and name. These can not be filtered and will be present in every response object.
- -
- -
-
RESTful HTTP calls are the main interface. A client does not necessarily have to register for events, it can also use plain HTTP polling. A polling client will not be automatically updated with the server state. API-Calls that change the server state are responded with a StatusObject only. The altered state has to be accessed via HTTP_GET or by event subscription.
-
+ -
+
The depth of the URI tree is limited to 3, i.e.
+/<service>/<resource>/<element>. While<service>and<resource>are predefined in this document,<element>will always be an identifier or the keyword$accessrights,$idor$spec.<resource>is always a collection (e.g stations) and thus has to be a noun plural form, even if the<resource>will only carry one single<element>by design. The<resource>identifiers must not carry verbs likegetAccountorcreateTrack.
+ -
+
An event is considered 'on change' if two subsequent GET requests - with no expansion applied (see Expansion concept) - on the corresponding URI would result in different responses. If an elements property 'name' is changed, an 'on change' event is fired (Publish Subscribe). Example: Only if an element is added or removed from a list of objects (on resource level), an 'on change' event is fired (Publish Subscribe). If a client wants to get notified on nested properties or structures, the corresponding event has to be subscribed individually at element level.
+
+ -
+
To keep the overall network traffic at a minimum, every resource and element access supports filtering. The response filtering concepts "fields", "paging" and "expand" are generally available.
+
+ -
+
Every object inherits from XObject. I.e. every Object has three mandatory properties: id, uri and name. These properties will be present in every response object.
+ +
+ RESTful HTTP calls are the main interface. A client does not necessarily have to register for events, it can also use plain HTTP polling. A polling client will not be automatically updated with the server state. API-Calls that change the server state are responded with a StatusObject only. The altered state has to be accessed via HTTP_GET or by event subscription.
+
- HTTP status codes
-All web services have to follow the W3C/IANA HTTP status code specification (HTTP/1.1 status codes, 2012, RFC2616).
-This section extends each Status-Code with implication and handling information for a client. The general meaning of status codes remains untouched. The client has to work with any response with a status code defined in RFC2616. In addition to the general RFC2616 status code definitions, some status codes are generally not expected by the client, those codes are marked as not applicable in viwi context. Each status code may have a domain specific meaning, which will be described in the according domain section separately. Please note that each service domain may overwrite the implication and client-side treatment.
+HTTP status codes
+All services have to follow the W3C/IANA HTTP status code specification (Hypertext Transfer Protocol (HTTP) Status Code Registry).
+This section extends each Status-Code with implication and handling information for a client. The general meaning of status codes remains untouched. The client has to be able to work with any response with a status code defined in RFC6585, RFC7231 and RFC7725. In addition to the status code definitions, some status codes are generally not expected by the client, those codes are marked as not applicable in viwi context. Each status code may have a domain specific meaning, which will be described in the according domain section separately. Please note that each service domain may overwrite the implication and client-side treatment.
| Code | -name | -Implication | -Client-side treatment | -
|---|---|---|---|
| 100 | -Continue | -Not applicable. | -None | -
| 101 | -Switching Protocols | -Only used for establishing websockets, see RFC6455 section 4.2.2. | -None | -
| 200 | -OK | -Used for successful HTTP Requests. This code is used to acknowledge successful change of the resource or element. | -None | -
| 201 | -Created | -Used for successfully creating new entities. | -None | -
| 202 | -Accepted | -The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon. There is no guarantee that the request will be fullfilled. | -Subscribe to affected entity, if the actual outcome is of interest. | -
| 203 | -Non-Authoritative Information | -Not applicable. | -None | -
| 204 | -No Content | -Not applicable. | -None | -
| 205 | -Reset Content | -Not applicable. | -None | -
| 206 | -Partial Content | -Not applicable. | -None | -
| 300 | -Multiple Choices | -Used if multiple services match the request criteria (service registry only) | -Client has to select and re-request | -
| 301 | -Moved Permanently | -Not applicable, see service registry. | -None | -
| 302 | -Found | -Not applicable. | -None | -
| 303 | -See Other | -Not applicable. | -None | -
| 304 | -Not Modified | -If the entity is not modified, this status code can be sent. This indicates that the client should look for this entity in its cache. | -None | -
| 305 | -Use Proxy | -Not applicable. | -None | -
| 306 | -Unused | -Not applicable, see status code 306. | -None | -
| 307 | -Temporary Redirect | -The requested resource has moved. The new location is send as an absolute URL in the response HTTP-Header Location field. |
- Client should submit a new HTTP request. | -
| 400 | -Bad Request | -The client submitted a malformed request, repeating the request will not help. | -Client has to make sure to send a valid request. | -
| 401 | -Unauthorized | -This request requires authentication. | -If client is not authenticated, client has to authenticate. | -
| 402 | -Payment Required | -Not applicable. | -None | -
| 403 | -Forbidden | -The client has insufficient rights to obtain the requested information or has submitted an HTTP request with POST method to a property, which is read-only or not allowed to be set by the client(e.g. POST on /car/info property vehicleIdentication). |
- If client do not have access rights, client has to acquire access rights. | -
| 404 | -Not Found | -The service cannot find the entity, this may be a permanent or temporary condition. Do not expect elements to be generally available. This status code is treated as a valid response. Use-case specific error handling is required. | -None | -
| 405 | -Method Not Allowed | -Not applicable, because all possible HTTP-Methods are defined by the the viwi document and missing privileges are singnaled by status code 403. | -None | -
| 406 | -Not Acceptable | -Not applicable. | -None | -
| 407 | -Proxy Authentication Required | -Not applicable. | -None | -
| 408 | -Request Time-out | -Not applicable. The request sent to the server took longer than the server was prepared to wait. In other words, client connection with server "timed out". Server configuration should rule out this error. | -None | -
| 409 | -Conflict | -It is not possible to establish the required state. This might be the case if a client wants to set an objects property that is not writable or that currently can not be set. The message property of StatusObject may have information for the client to recognize the source of the conflict. This information is only for debugging and development purposes. |
- Resource specific treatment is necessary (e.g. media audioSource might be disabled during navigation announcements, the clients tries to un-mute media). See status code 409 for more information. | -
| 410 | -Gone | -Not applicable. | -None | -
| 411 | -Length Required | -Not applicable, see status code 411. | -None | -
| 412 | -Precondition Failed | -Not applicable. | -None | -
| 413 | -Request Entity Too Large | -Not applicable, see paging. | -None | -
| 414 | -Request-URI Too Large | -Not applicable, see RFC2616 section 3.2.1. | -None | -
| 415 | -Unsupported Media Type | -Not applicable. | -None | -
| 416 | -Requested range not satisfiable | -Not applicable. | -None | -
| 417 | -Expectation Failed | -Not applicable. | -None | -
| 418 | -I’m a teapot | -Not applicable. | -None | -
| 420 | -Policy Not Fulfilled | -Not applicable. | -None | -
| 421 | -Misdirected Request | -Not applicable. | -None | -
| 422 | -Unprocessable Entity | -Not applicable. | -None | -
| 423 | -Locked | -Not applicable. | -None | -
| 424 | -Failed Dependency | -Not applicable. | -None | -
| 429 | -Too Many Requests | -The user has sent too many requests in a given amount of time. | -Used to rate-limit access to a certain resource or element | -
| 451 | -Unavailable For Legal Reasons | -A server operator has received a legal demand to deny access to a resource or to a set of resources that includes the requested resource. | -Sent, when for any legal reason access to a resource or element is (temporarily) blocked | -
| 500 | -Internal Server Error | -The server encountered an unexpected condition which prevented it from fulfilling the request. | -There is no client-side fix/solution for this kind of errors. | -
| 501 | -Not Implemented | -The server does not support the functionality required to fulfill the request. Unless specified otherwise in service specific status code handling, this error indicates a not-permitted error. | -Not applicable. | -
| 502 | -Bad Gateway | -Not applicable. | -None | -
| 503 | -Service Unavailable | -Service is currently unable to handle the request. This implies a temporary problem which will be solved after a given delay. If known, the delay may be indicated in a Retry-After header. |
- Client should retry to submit the request after delay. | -
| 504 | -Gateway Time-out | -The request can not be fulfilled because server acts as a proxy and did not receive a timely response from remote component (e.g. ECU of driver assistance). | -There is no client-side fix/solution for this kind of error. If the remote component expected to be reachable after a delay in this power-cycle then server sends a response with status code 503. | -
| 505 | -HTTP Version not supported | -Not applicable. | -None | -
| Code | +name | +Implication | +Client-side treatment | +
| 100 | +Continue | +Not applicable. | +None | +
| 101 | +Switching Protocols | +Only used for establishing websockets, see RFC6455 section 4.2.2. | +None | +
| 200 | +OK | +Used for successful HTTP Requests. This code is used to acknowledge successful change of the resource or element. | +None | +
| 201 | +Created | +Used for successfully creating new entities. | +None | +
| 202 | +Accepted | +The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon. There is no guarantee that the request will be fullfilled. | +Subscribe to affected entity, if the actual outcome is of interest. | +
| 203 | +Non-Authoritative Information | +Not applicable. | +None | +
| 204 | +No Content | +Not applicable. | +None | +
| 205 | +Reset Content | +Not applicable. | +None | +
| 206 | +Partial Content | +Not applicable. | +None | +
| 300 | +Multiple Choices | +Used if multiple services match the request criteria (service registry only) | +Client has to select and re-request | +
| 301 | +Moved Permanently | +Not applicable, see service registry. | +None | +
| 302 | +Found | +Not applicable. | +None | +
| 303 | +See Other | +Not applicable. | +None | +
| 304 | +Not Modified | +If the entity is not modified, this status code can be sent. This indicates that the client should look for this entity in its cache. | +None | +
| 305 | +Use Proxy | +Not applicable. | +None | +
| 307 | +Temporary Redirect | +The requested resource has moved. The new location is send as an absolute URL in the response HTTP-Header Location field. |
+ Client should submit a new HTTP request. | +
| 400 | +Bad Request | +The client submitted a malformed request, repeating the request will not help. | +Client has to make sure to send a valid request. | +
| 401 | +Unauthorized | +This request requires authentication. | +If client is not authenticated, client has to authenticate. | +
| 402 | +Payment Required | +Not applicable. | +None | +
| 403 | +Forbidden | +The client has insufficient rights to obtain the requested information or has submitted an HTTP request with POST method to a property, which is read-only or not allowed to be set by the client(e.g. POST on /car/info property vehicleIdentication). |
+ If client do not have access rights, client has to acquire access rights. | +
| 404 | +Not Found | +The service cannot find the entity, this may be a permanent or temporary condition. Do not expect elements to be generally available. This status code is treated as a valid response. Use-case specific error handling is required. | +|
| 405 | +Method Not Allowed | +Not applicable, because all possible HTTP-Methods are defined by the the viwi document and missing privileges are singnaled by status code 403. | +None | +
| 406 | +Not Acceptable | +Not applicable. | +None | +
| 407 | +Proxy Authentication Required | +Not applicable. | +None | +
| 408 | +Request Time-out | +Not applicable. The request sent to the server took longer than the server was prepared to wait. In other words, client connection with server "timed out". Server configuration should rule out this error. | +None | +
| 409 | +Conflict | +It is not possible to establish the required state. This might be the case if a client wants to set an objects property that is not writable or that currently can not be set. The message property of StatusObject may have information for the client to recognize the source of the conflict. This information is only for debugging and development purposes. |
+ Resource specific treatment is necessary (e.g. media audioSource might be disabled during navigation announcements, the clients tries to un-mute media). See RFC7231 section 6.5.8 for more information. | +
| 410 | +Gone | +Not applicable. | +None | +
| 411 | +Length Required | +Not applicable, see RFC7231 section 6.5.10. | +None | +
| 412 | +Precondition Failed | +Not applicable. | +None | +
| 413 | +Request Entity Too Large | +Not applicable, see paging. | +None | +
| 414 | +Request-URI Too Large | +Not applicable, see RFC7231 section 6.5.12. | +None | +
| 415 | +Unsupported Media Type | +Not applicable. | +None | +
| 416 | +Requested range not satisfiable | +Not applicable. | +None | +
| 417 | +Expectation Failed | +Not applicable. | +None | +
| 426 | +Upgrade Required | +Not applicable. | +None | +
| 428 | +Precondition Required | +Not applicable. | +None | +
| 429 | +Too Many Requests | +The user has sent too many requests in a given amount of time. | +Used to rate-limit access to a certain resource or element | +
| 431 | +Request Header Fields Too Large | +Client send header fields which are to large or not correctly formated | +Send smaller and correct header fields | +
| 451 | +Unavailable For Legal Reasons | +A server operator has received a legal demand to deny access to a resource or to a set of resources that includes the requested resource. | +Sent, when for any legal reason access to a resource or element is (temporarily) blocked | +
| 500 | +Internal Server Error | +The server encountered an unexpected condition which prevented it from fulfilling the request. | +There is no client-side fix/solution for this kind of errors. | +
| 501 | +Not Implemented | +The server does not support the functionality required to fulfill the request. Unless specified otherwise in service specific status code handling, this error indicates a not-permitted error. | +Not applicable. | +
| 502 | +Bad Gateway | +Not applicable. | +None | +
| 503 | +Service Unavailable | +Service is currently unable to handle the request. This implies a temporary problem which will be solved after a given delay. If known, the delay may be indicated in a Retry-After header. |
+ Client should retry to submit the request after delay. | +
| 504 | +Gateway Time-out | +The request can not be fulfilled because server acts as a proxy and did not receive a timely response from remote component (e.g. ECU of driver assistance). | +There is no client-side fix/solution for this kind of error. If the remote component is expected to be reachable after a delay in this power-cycle then server sends a response with status code 503. | +
| 505 | +HTTP Version not supported | +Not applicable. | +None | +
| 511 | +Network Authentication Required | +The connection to the vehicle infrastructure is not authenticated. | +Reauthenticate the connection channel. | +
Handling service responses with respecting status codes
-To communicate with the services a client submits an HTTP request and waits for the response. A response is always sent with a status code. The service uses the pre-defined status codes when sending a response. Each client interpret the response with the respective status code.
+To communicate with the services a client submits an HTTP request and waits for the response. A response is always sent with a status code. The service uses the pre-defined status codes when sending a response. Each client interprets the response with the respective status code.
Each status code is categorized as successful (2xx), redirection (3xx), client error (4xx) or server error (5xx). If status code is not successful, then the response must be handled by the client as following:
- If an error can be treated by a client, it is categorized as permitted errors. For each permitted error a treatment is defined.
- If an error can not be treated by the client, it is categorized as not permitted error. -
- Each service domain may overwrite permitted and not permitted errors. +
- Each service domain may define, which errors are permitted and not permitted.
RESTful API
General information
The REST architectural style describes six constraints:
-
-
- uniform interface (resource based, self descriptive, ...) -
- statelessness (necessary state to handle the request is contained within the request itself) -
- cacheability (clients can cache responses) -
- client-server architecture (uniform interface separates client and server) -
- layered system (client cannot ordinarily tell whether it is connected directly or intermediary) -
- code on demand
optional(Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it)
+ - uniform interface (resource based, self descriptive, ...) +
- statelessness (necessary state to handle the request is contained within the request itself) +
- cacheability (clients can cache responses) +
- client-server architecture (uniform interface separates client and server) +
- layered system (client cannot ordinarily tell whether it is connected directly or intermediary) +
- code on demand
optional(Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it)
Conforming to the REST architectural style, will enable any kind of distributed system to have desirable emergent characteristics, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.
These constraints, applied to the architecture, were originally communicated by Roy Fielding in his doctoral dissertation and define the basis of RESTful-style.
-Source: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.html
+Source: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
Uniform interface
The uniform interface constraint defines the interface between clients and servers. It simplifies and decouples the architecture, which enables each part to evolve independently. The four guiding principles of the uniform interface are:
Resource-based
-Individual resources are identified in requests using URIs as - resource identifiers. The resources themselves are conceptually - separate from the representations that are returned to the - client. For example, the server does not send its database, but - rather, some HTML, XML or JSON that represents some database - records. For instance data for a finnish client, in Finnish - language and encoded in UTF-8, depending on the details of the request and the server implementation.
+Individual resources are identified in requests using URIs as resource identifiers. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, some HTML, XML or JSON that represents some database records. For instance data for a finish client, in Finnish language and encoded in UTF-8, depending on the details of the request and the server implementation.
Manipulation of resources through representations
When a client holds a representation of a resource, including any meta data attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so.
Self-descriptive messages
Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cache-ability.
Hypermedia as the engine of application state (HATEOAS)
-Clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). Services deliver state to clients via body content, response codes, and response headers. This is technically referred-to as hypermedia (or hyperlinks within hypertext). Aside from the description above, HATEOS also means that, where necessary, links are contained in the returned body (or headers) to supply the URI for retrieval of the object itself or related objects. We'll talk about this in more detail later.
+Clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). Services deliver state to clients via body content, response codes, and response headers. This is technically referred-to as hypermedia (or hyperlinks within hypertext). + Aside from the description above, HATEOAS also means that, where necessary, links are contained in the returned body (or headers) to supply the URI for retrieval of the object itself or related objects.
The uniform interface that any REST services must provide is fundamental to its design.
Statelessness
-As REST is an acronym for REpresentational State Transfer, - statelessness is key. Essentially, what this means is that the - necessary state to handle the request is contained within the - request itself, whether as part of the URI, query-string - parameters, body, or headers. The URI uniquely identifies the - resource and the body contains the state (or state change) of - that resource. Then after the server does it's processing, the - appropriate state, or the piece(s) of state that matter, are - communicated back to the client via headers, status and response - body. Classical - statefull - API design provides us with the - concept of programming within a container which maintains state - across multiple HTTP requests. In REST, the client must include - all information for the server to fulfill the request, resending - state as necessary if that state must span multiple - requests. Statelessness enables greater scalability since the - server does not have to maintain, update or communicate that - session state. Additionally, load balancers don't have to worry - about session affinity for stateless systems. So what's the - difference between state and a resource? State, or application - state, is that which the server cares about to fulfill a request - - data necessary for the current session or request. A resource, or resource state, is the data that defines the resource representation — the data stored in the database, for instance. Consider application state to be data that could vary by client, and per request. Resource state, on the other hand, is constant across every client who requests it. Ever had back-button issues with a web application where it went AWOL (Absent Without Official Leave - military jargon) at a certain point because it expected you to do things in a certain order? That's because it violated the statelessness principle. There are cases that don't honor the statelessness principle, such as three-legged OAuth, API call rate limiting, etc. However, make every effort to ensure that application state doesn't span multiple requests of your service(s).
+As REST is an acronym for REpresentational State Transfer, statelessness is key. Essentially, what this means is that the necessary state to handle the request is contained within the request itself, whether as part of the URI, query-string parameters, body, or headers. The URI uniquely identifies the resource and the body contains the state (or state change) of that resource. Then after the server does it's processing, the appropriate state, or the piece(s) of state that matter, are communicated back to the client via headers, status and response body. + Classical - statefull - API design provides us with the concept of programming within a container which maintains state across multiple HTTP requests. In REST, the client must include all information for the server to fulfill the request, resending state as necessary if that state must span multiple requests. Statelessness enables greater scalability since the server does not have to maintain, update or communicate that session state. Additionally, load balancers don't have to worry about session affinity for stateless systems. + So what's the difference between state and a resource? State, or application state, is the one which the server cares about to fulfill a request - data necessary for the current session or request. A resource, or resource state, is the data that defines the resource representation — the data stored in the database, for instance. Consider application state to be data that could vary by client, and per request. Resource state, on the other hand, is constant across every client who requests it. + Ever had back-button issues with a web application where it went AWOL (Absent Without Official Leave - military jargon) at a certain point because it expected you to do things in a certain order? That's because it violated the statelessness principle. There are cases that don't honor the statelessness principle, such as three-legged OAuth, API call rate limiting, etc. However, make every effort to ensure that application state doesn't span multiple requests of your service(s).
Cacheability
As on the World Wide Web, clients can cache responses. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing stale or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client-server interactions, further improving scalability and performance.
Client-server architecture
@@ -863,205 +820,229 @@Layered system
Code-on-demand optional
Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.
Application to viwi
-The interfaces described inhere follow the RESTful (REST: Representational State Transfer) principles. The main concept in REST is the existence of resources (sources of specific information or services), each of which is referenced with a uri as global identifier. The RESTful API is used to retrieve information for the client (request) from the server (response), while Events provide a channel for communication in server to client direction (push information). The supported HTTP request methods are GET, POST, PUT and DELETE. The following table explains the main principle of interface definition for all services defined hereafter:
The interfaces described inhere follow the RESTful principles. The main concept in REST is the existence of resources (sources of specific information or services), each of which is referenced with a uri as global identifier. The RESTful API is used to retrieve information for the client (request) from the server (response), while Events provide a channel for communication in server to client direction (push information). The supported HTTP request methods are GET, POST, PUT and DELETE. The following table explains the main principle of interface definition for all services defined hereafter:
| - | HTTP | -HTTP | -HTTP | -HTTP | -WebSocket | ++ type + | ++ GET (HTTP) | ++ POST (HTTP) | ++ PUT (HTTP) | ++ DELETE (HTTP) | ++ subscribe (WebSocket) |
|---|---|---|---|---|---|---|---|---|---|---|---|
| type | -GET | -POST | -PUT | -DELETE | -subscribe | -||||||
root URI, such as / or /api/v1/ |
- List the URIs and perhaps other details of the service known to the system. | +root URI, such as
+ / or
+ /api/v1/
+ |
+ + List the URIs and perhaps other details of the service known to the system. | n/a | -Register new service with the system. The new service's URI is assigned automatically and is returned by the operation. | ++ Register new service with the system. The new service's URI is assigned automatically and is returned by the + operation. | n/a | -Get updated on collection changes (e.g. add, delete of elements) | +Get updated on + collection changes (e.g. addition, removal of elements) | ||
service URI, such as /<service>/ |
- List the URIs and perhaps other details of the service resources. | -Create new resource within the service. The new resource's URI is assigned automatically and is returned by the operation. | +service URI, such as
+ /<service>/
+ |
+ + List all elements matching the request (including query parameters). | n/a | -De-Register new service with the system. <service> has to be accessed by its uuid. (special permissions needed) |
- Get updated on collection changes (e.g. add, delete of elements) | -||||
Resource URI, such as /<service>/<resource>/ |
- List the URIs and perhaps other details of the collection's members. | -Create new element in collection or simultaneously change a collecton of elements. The new element's URI is assigned automatically and is returned by the operation. | n/a | +
+ De-Register new service with the system.
+ <service> has to be accessed by its uuid. (special permissions needed) |
+ Get updated on + collection changes (e.g. addition, removal of elements) | +||||||
Resource URI, such as
+ /<service>/<resource>/
+ |
+ + List the URIs and perhaps other details of the collection's members. | ++ Create new element in collection or simultaneously + change a collecton of elements. The new element's URI is assigned automatically and is returned by the operation. | n/a | -Get updated on collection changes (e.g. add, delete of elements) | -|||||||
Element URI, such as /<service>/<resource>/<element> |
- Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type. | -Update element. The updated element's URI is assigned automatically and is returned by the operation. | -Create new element in collection by sending the entire entity. The new element's URI is assigned accordingly. | -Delete the referred entity of the collection (or its attributes) | -Get updated on element changes (e.g. playing tracks offset on media player) | +n/a | +Get updated on + collection changes (e.g. addition, removal of elements) | +||||
Element URI, such as
+ /<service>/<resource>/<element>
+ |
+ + Retrieve a representation of the addressed + member of the collection, expressed in an appropriate Internet media type. | ++ Update element. The updated element's URI is assigned automatically and is returned by the operation. | ++ Create new element in collection by sending the entire entity. The new element's URI is assigned accordingly. | ++ Delete the referred entity of the collection (or its attributes) | +Get updated on + element changes (e.g. playing tracks offset on media player) |
HEAD
-The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The meta information contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining meta information about the entity implied by the request without transferring the entity-body itself. The method is often used to obtain information about expiry or existence, specially in cases where cross origin resource sharing (CORS) is needed.
The HEAD(see RFC7231 section 4.3.2) method is identical to GET except that the server MUST NOT return a message-body in the response. The meta information contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining meta information about the entity implied by the request without transferring the entity-body itself. The method is often used to obtain information about expiry or existence, specially in cases where cross origin resource sharing (CORS) is needed.
DELETE
A client can either delete entire <element>s or just properties on the <element>s properties specified in the $fields query parameters. The mandatory fields id, name and uri can not be deleted. In case of a writable name property on an <element>, a client can reset the name to "" by POSTing.
Example element deletion
request:
-DELETE medialibrary/tracks/01ACEB4B-002D-4060-A8EB-81868BF0BC37 HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-response:
+DELETE /medialibrary/tracks/01aceb4b-002d-4060-a8eb-81868bf0bc37 HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+ response:
HTTP/1.1 200 OK
-X-Powered-By: Express
-Vary: Accept-Encoding
-Content-Type: application/json; charset=utf-8
-ETag: "-32550834"
-Content-Encoding: gzip
-Date: Tue, 13 Jun 2014 19:47:27 GMT
-Connection: keep-alive
-Transfer-Encoding: chunked
-
-
-{
- "status" : "ok"
-}
-Example deletion of element properties artists and rating
+ X-Powered-By: Express + Vary: Accept-Encoding + Content-Type: application/json; charset=utf-8 + ETag: "-32550834" + Content-Encoding: gzip + Date: Tue, 13 Jun 2014 19:47:27 GMT + Connection: keep-alive + Transfer-Encoding: chunked + + + { + "status" : "ok" + } +Example deletion of element properties artists and rating
request:
-DELETE medialibrary/tracks/01ACEB4B-002D-4060-A8EB-81868BF0BC37?$fields=artists,rating HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-response:
+DELETE /medialibrary/tracks/01aceb4b-002d-4060-a8eb-81868bf0bc37?$fields=artists,rating HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+ response:
HTTP/1.1 200 OK
-X-Powered-By: Express
-Vary: Accept-Encoding
-Content-Type: application/json; charset=utf-8
-ETag: "-32550834"
-Content-Encoding: gzip
-Date: Tue, 13 Jun 2014 19:47:27 GMT
-Connection: keep-alive
-Transfer-Encoding: chunked
-
-
-{
- "status" : "ok"
-}
-POST
+ X-Powered-By: Express + Vary: Accept-Encoding + Content-Type: application/json; charset=utf-8 + ETag: "-32550834" + Content-Encoding: gzip + Date: Tue, 13 Jun 2014 19:47:27 GMT + Connection: keep-alive + Transfer-Encoding: chunked + + + { + "status" : "ok" + } +POST
Creating or changing an entity should always be done in the most condensed way (one request) possible, except the client explicitly wants to execute a sequence.
Creating e.g. an element is possible by providing no additional information in some cases and later in time modifying the newly created element to the desired state is possible. Nevertheless, providing all known information with the initial request ensures object integrity and minimum network traffic at the same time.
Changing an element's properties subsequently may cause unwanted effects like flickering in the maprenderer's case or jumps in the mediarenderer's case.
-The protocol is based on the last-wins principal, i.e. last update arriving at the server determines the final state, disregarding the actual time gap between arrival of two subsequent requests.
-POST to change a collection of elements
-In order to allow simultaneous updates on different elements, combining query parameters as known from a GET request with a POST query on <resource> is used. The idea behind is that a query will select a sub-collection (filter) of the <resource>s elements for which the POST action shall be applied. This is particulary useful, for multi-element-transactions such as setting the color of multiple lights simultaneously. The request will only return a success if all changes were applied successfully, it will fail and return an appropriate code otherwise.
Light decoration example
-Assuming a desire to change the light color of LEDs simultaneously for two decoration elements with the ids 0dde0b53-b862-44ec-bab2-045c049d220c and 1ca1b74-da9a-4933-baa5-1d6f0669dad0, a combined request would be sent instead of two subsequent ones.
- +The protocol is based on the last-wins principle, i.e. last update arriving at the server determines the final state, disregarding the actual time gap between arrival of two subsequent requests.
+DELETE collection of elements
+In order to allow simultaneous deletion of different elements, combining query parameters as known from a GET request with a DELETE query on <resource> is used. The idea behind is that a query will select a sub-collection (filter) of the <resource>s elements for which the DELETE action shall be applied. The request will only return a success if all deletions were successful, it will fail and return an appropriate code otherwise.
request:
-GET dashboard/decoration/?id=0dde0b53-b862-44ec-bab2-045c049d220c,1ca1b74-da9a-4933-baa5-1d6f0669dad0 HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-
-
-{
- "color": "blue"
-}
-response:
+DELETE /addressbook/contacts/?id=34a96130-4beb-47ed-b5e5-5a835907e0eb,2fb85b19-6eb6-49c1-87c5-dcb987aa23d6 HTTP/1.1
+ Host: 127.0.0.1:1337
+ Accept: application/json
+ Accept-Encoding: gzip,deflate
+ response:
HTTP/1.1 200 OK
-X-Powered-By: Express
-Vary: Accept-Encoding
-Content-Type: application/json; charset=utf-8
-ETag: "-32550834"
-Content-Encoding: gzip
-Date: Tue, 13 Jun 2014 19:47:27 GMT
-Connection: keep-alive
-Transfer-Encoding: chunked
-
-
-{
- "status" : "ok"
-}
-- Caching
+ Vary: Accept-Encoding + Content-Type: application/json; charset=utf-8 + Content-Encoding: gzip + + + { + "status" : "ok" + } +POST to change a collection of elements
+In order to allow simultaneous updates on different elements, combining query parameters as known from a GET request with a POST query on <resource> is used. The idea behind is that a query will select a sub-collection (filter) of the <resource>s elements for which the POST action shall be applied. This is particularly useful for multi-element-transactions such as setting the color of multiple lights simultaneously. The request will only return a success if all changes were applied successfully, it will fail and return an appropriate code otherwise.
Light decoration example
+Assuming a desire to change the light color of LEDs simultaneously for two decoration elements with the ids 0dde0b53-b862-44ec-bab2-045c049d220c and 1ca1b74-da9a-4933-baa5-1d6f0669dad0, a combined request would be sent instead of two subsequent ones.
+request:
+POST /dashboard/decoration/?id=0dde0b53-b862-44ec-bab2-045c049d220c,1ca1b74-da9a-4933-baa5-1d6f0669dad0 HTTP/1.1
+ Host: 127.0.0.1:1337
+ Accept: application/json
+ Accept-Encoding: gzip,deflate
+
+
+ {
+ "color": "blue"
+ }
+ response:
+HTTP/1.1 200 OK
+ Vary: Accept-Encoding
+ Content-Type: application/json; charset=utf-8
+ Content-Encoding: gzip
+
+
+ {
+ "status" : "ok"
+ }
+ Caching
Cache control is established by using HTTP headers ETag and If-None-Match (cmp. RFC 7232-2.3). Mainly used for web cache validation, a client can make conditional requests based on the response. This allows caches to be more efficient, saves bandwidth and avoid cache-sync problems as a service does not need to send a full response if the content has not changed and a client can use the cached information. This also applies to service-service communication, especially when service A references element owned by service B. A will act as a client and use its own cached information if no changes where detected by B.
The basic sequence is: First: ask for an entity
+The basic sequence is: + First: ask for an entity
request:
-GET cdn/images/foo.png HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: image/*
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-response:
+GET /cdn/images/foo.png HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: image/*
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+ response:
HTTP/1.1 200 OK
-Content-Type: image/png
-ETag: "641abf"
-Content-Encoding: gzip
-Date: Tue, 13 Jun 2014 19:47:27 GMT
-Connection: keep-alive
-Transfer-Encoding: chunked
-Content-Length: 15360
-
-
-<base64encodedfile>
-The client uses the content delivered with the response, stores the ETag info with the entity in its cache.
The client uses the content delivered with the response, stores the ETag info with the entity in its cache.
Second: later ask for the same entity together with If-None-Match
GET cdn/images/foo.png HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-If-None-Match: "641abf"
-Accept: image/*
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-response:
+GET /cdn/images/foo.png HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ If-None-Match: "641abf"
+ Accept: image/*
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+ response:
HTTP/1.1 304 Not Modified
-Content-Type: image/png
-ETag: "641abf"
-Content-Encoding: gzip
-Date: Tue, 13 Jun 2014 21:47:27 GMT
-Connection: keep-alive
-Transfer-Encoding: chunked
-Content-Length: 0
-The client uses the information from its cache, 0 bytes of payload were transfered.
+ Content-Type: image/png + ETag: "641abf" + Content-Encoding: gzip + Date: Tue, 13 Jun 2014 21:47:27 GMT + Connection: keep-alive + Transfer-Encoding: chunked + Content-Length: 0 +The client uses the information from its cache, 0 bytes of payload were transfered.
AND vs. OR queries
Queries are treated as OR queries per query parameter, i.e. GET /api/v1/<service>/<resource>/?name=foo,bar will retrieve all elements whose names equals 'foo' OR 'bar'. Using multiple query parameters on the other hand is treated as an AND query, e.g. GET /api/v1/<service>/<resource>/?name=foo&type=bar retrieves all elements named 'foo', being of type 'bar'. To obtain elements by OR queries over multiple query parameters, multiple queries are needed to be made and being combined by the client. This also applies to $expand, $fields etc.
GET /api/v1/<service>/<resource>/?$expand=foo,bar reads like 'please expand the properties whose name is either foo OR bar'. GET /api/v1/<service>/<resource>/?name=foo,bar reads like 'give me only those properties whose name is either foo OR bar'.
Request response content
The response is always of contentType: application/json (or application/vnd.viwi.v<major>.<minor>.<patch>+json) with charset=UTF-8, expect for binary content. Binary content uses regular HTTP headers according to its MIME-type.
POST requests only accept payload in the body, no form encoded (HEADER) data is accepted.
Graph interface
-A fundamental concept of the API is the graph. All objects can get into relation with each other. The objects can be understood as nodes in a graph while the relations between them are the edges in this graph. This relation is expressed by referencing from one object to another in the object structure. For example, a 'media renderer' (node) may 'have' (edge) a 'mediaCollection' (node). The 'mediaCollection' (node) itself may 'contain' (edge) multiple items like a 'track' (node) or a 'video' (node).
+A fundamental concept of the API is the graph. All objects can get into relation with each other. The objects + can be understood as nodes in a graph while the relations between them are the edges in this graph. This relation is expressed by referencing from one object to another in the object structure. For example, a 'media + renderer' (node) may 'have' (edge) a 'mediaCollection' (node). The 'mediaCollection' (node) itself may + 'contain' (edge) multiple items like a 'track' (node) or a 'video' (node).
Response filtering
Reserved query parameters
An API-query or subscription can contain none, one or multiple parameters that represent the desire to filter a query. All parameters that do not point to an object property, but have a general nature, are prefixed with $. The following paragraphs make use of this rule and give examples.
Resource search
-A search can be performed on any resource, as either freetext search, parameter search or a combination of both. The parameter search is performed by using request parameters according to the properties of the resources object. The request parameters name has to resemble the objects property name, while its value is the search key. The character "%" (URL encoded: %25) is used as wildcard and can be used anywhere in the search key. It is possible to combine multiple request parameters in a single search, while combining multiple search keys in a single request is not supported. Thus, a search query always returns the result of an AND query. http://127.0.0.1:1337/medialibrary/tracks/?$q=5&artists=CB4E5462-1DDF-46C1-9B9D-45D6008A1989 reads as 'fetch all tracks from the medialibrary that have any property set to 5 AND the the artists property contains CB4E5462-1DDF-46C1-9B9D-45D6008A1989'. To perform an OR query, multiple query have to be combined on client side.
A search can be performed on any resource, as either freetext search, parameter search or a combination of both. The parameter search is performed by using request parameters according to the properties of the resources object. The request parameters name has to resemble the objects property name, while its value is the search key. The character "%" (URL encoded: %25) is used as wildcard and can be used anywhere in the search key. Searches are only possible on properties which reference an XObject or primitive or arrays of those (i.e. searches are not possible on properties that are inlined objects). It is possible to combine multiple request parameters in a single search, while combining multiple search keys in a single request is not supported. Thus, a search query always returns the result of an AND query. http://127.0.0.1:1337/medialibrary/tracks/?$q=5&artists=cb4e5462-1ddf-46c1-9b9d-45d6008a1989 reads as 'fetch all tracks from the medialibrary that have any property set to 5 AND the the artists property contains cb4e5462-1ddf-46c1-9b9d-45d6008a1989'.
+ To perform an OR query, multiple query have to be combined on client side.
Property search
request:
-GET medialibrary/tracks/?rating=5 HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-response:
+GET /medialibrary/tracks/?rating=5 HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+ response:
HTTP/1.1 200 OK
X-Powered-By: Express
Vary: Accept-Encoding
@@ -1152,15 +1136,14 @@ Property search
A freetext search is performed by using the request parameter $q. The search key will be tested against any property value. Freetext search also supports wildcard character "%" (URL encoded: %25).
Example freetext
request:
- GET medialibrary/tracks/?$q=me%20and%20my%20empty%20wallet HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-
- response:
+ GET /medialibrary/tracks/?$q=me%20and%20my%20empty%20wallet HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+
response:
HTTP/1.1 200 OK
X-Powered-By: Express
Vary: Accept-Encoding
@@ -1210,15 +1193,14 @@ Example freetext
Referenced object
To search for a linked object, use its <uuid> as search value on the search key of its property name.
request:
- GET medialibrary/tracks/?artists=bb3372f0-b527-11e3-a5e2-0800200c9a66 HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-
- response:
+ GET /medialibrary/tracks/?artists=bb3372f0-b527-11e3-a5e2-0800200c9a66 HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+
response:
HTTP/1.1 200 OK
X-Powered-By: Express
Vary: Accept-Encoding
@@ -1271,14 +1253,11 @@ Sorting
Similar to searching, a generic parameter $sortby can be used for GET requests on resource level to describe sorting rules. Accommodate complex sorting requirements by letting the sort parameter take in a list of comma separated fields, each with a possible unary negative to imply descending sort order.
Every <resource> has a fixed default ordering, i.e. statelessness is given by defining a default sort behavior per <resources>, the $sortby parameter just over-rules the default behavior.
http://127.0.0.1:1337/medialibrary/tracks/?$sortby=rating
-
- or
+
or
http://127.0.0.1:1337/medialibrary/tracks/?$sortby=-rating
-
- Sorting can be combined with searching by adding both request parameters to the query:
+
Sorting can be combined with searching by adding both request parameters to the query:
http://127.0.0.1:1337/medialibrary/tracks/?$sortby=rating&name=me%20an%my%20empty%20wallet
-
- Ordering by primitives
+ Ordering by primitives
Ordering by primitive value properties is possible alphabetical an numerical.
Ordering by complex objects
The default ordering by references to complex object is defined by the mandatory name member of the complex object. A service might implement a different behavior that has to be specified per service, if different to the default.
The expansion concept
Expansion does only work on JSON payload. If an object references to binary data, like images, expansion does NOT apply. Of course binary data can NOT be embedded into JSON payload and thus can not be expanded.
No expansion
request:
-GET medialibrary/albums/6149c270-b528-11e3-a5e2-0800200c9a66 HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-response:
+GET /medialibrary/albums/6149c270-b528-11e3-a5e2-0800200c9a66 HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+ response:
HTTP/1.1 200 OK
X-Powered-By: Express
Vary: Accept-Encoding
@@ -1363,15 +1341,14 @@ No expansion
Single property expansion
A client might want to expand just a single property on a given element. To achieve single property expansion, a client adds an $expand parameter followed by a comma separated list of property names.
request:
- GET medialibrary/albums/6149c270-b528-11e3-a5e2-0800200c9a66?$expand=artists HTTP/1.1
-Host: 127.0.0.1:1337
-Connection: keep-alive
-Accept: application/json
-User-Agent: Chrome/34.0.1847.137 Safari/537.36
-Accept-Encoding: gzip,deflate
-Accept-Language: en-US,en;q=0.8,de;q=0.6
-
- response:
+ GET /medialibrary/albums/6149c270-b528-11e3-a5e2-0800200c9a66?$expand=artists HTTP/1.1
+ Host: 127.0.0.1:1337
+ Connection: keep-alive
+ Accept: application/json
+ User-Agent: Chrome/34.0.1847.137 Safari/537.36
+ Accept-Encoding: gzip,deflate
+ Accept-Language: en-US,en;q=0.8,de;q=0.6
+
response:
HTTP/1.1 200 OK
X-Powered-By: Express
Vary: Accept-Encoding
@@ -1834,7 +1811,7 @@ Data
}
}
- Error
+ Error
If any error on the server side occurs an object with type ‘error’ is sent. The following JSON format shall be used:
{
"type" : "error",
@@ -2090,119 +2067,128 @@ binary content
Schema
All object properties make use JSON Schema definitions RFC7159. In addition to the formats defined in RFC7159 the date-time, date and time formats are derived but not identical to the definition in RFC3339. APIs may also use the following (proprietary) formats:
{
- "uuid": {
- "description": "unique identifier",
- "regex": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fAF]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
- "example": "388d3a25-663b-11e3-949a-0800200c9a66"
- },
- "geoposition": {
- "description": "latitude followed by longitude and altitude in meters separated by ';'",
- "regex": "^[-+]?[0-9]*\.?[0-9]*;[-+]?[0-9]*\.?[0-9]*;[-+]?[0-9]*\.?[0-9]*$",
- "example": "37.772323;-122.214897;0"
- },
- "e164telephonenumber": {
- "description": "E.164 encoded Telephone number",
- "regex": "^\+?\d{4,23}$",
- "example": "+49536190"
- },
- "macaddress": {
- "description": "device mac address",
- "regex": "^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$",
- "example": "a3:3E:ff:e3:01:fe"
- },
- "rgba": {
- "description": "rgba color with alpha",
- "regex": "^rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})(?:,\s*(\d(?:\.\d+)?))?\)$",
- "example": "rgba(25,9,19,0.4)"
- },
- "language": {
- "description": "HTTP1.1 compatible language tag",
- "regex": "^(\w{2})(-\w*)?$",
- "example": "en-gb"
- },
- "servicecategory": {
- "description": "plain string category name",
- "regex": "^[a-z]$",
- "example": "car"
- },
- "duration": {
- "description": "iso8601 duration",
- "regex": "^P\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$",
- "example": "P0003-06-04T12:30:05"
- },
- "temperatureUnit": {
- "description": "temperature measurement unit",
- "regex": "^[KCF]{1}$",
- "example": "C"
- },
- "distanceUnit": {
- "description": "distance unit",
- "regex": "^mi|km|yd|m|ft$",
- "example": "km"
- },
- "pressureUnit": {
- "description": "pressure measurement unit",
- "regex": "^bar|psi|kPa$",
- "example": "bar"
- },
- "volumeUnit": {
- "description": "volume measurement unit (ul = microliter)",
- "regex": "^l|ml|ul|gal$",
- "example": "ml"
- },
- "consumptionUnit": {
- "description": "consumption measurement unit (fluid, gas, electric)",
- "regex": "^l/100km|l/h|km/l|mpgUS|mpgUK|g/h|kg/100km|km/kg|kg/h|m3/100km|km/m3|m3/h|miles/lbs|lbs/h|miles/yard3|yard3/h|miles/kg|miles/m3|kWh/100km|km/kWh|kWh/100miles|miles/kWh|kW|Ws|miles/gal_eqUS$",
- "example": "l/h"
- },
- "weightUnit": {
- "description": "consumption measurement unit (fluid, gas, electric)",
- "regex": "^t|kg|g|mg|lbs$",
- "example": "kg"
- },
- "speedUnit": {
- "description": "speed unit",
- "regex": "^kmh|mph|m/s$",
- "example": "kmh"
- },
- "timeFormat": {
- "description": "the time format for clocks",
- "regex": "^12h|24h$",
- "example": "12h"
- },
- "dateFormat": {
- "description": "date format",
- "regex": "^ddmmyyyy|mmddyyyy|yyyymmdd$",
- "example": "mmddyyyy"
- },
- "date-time": {
- "description": "date-time (based on RFC3339 5.6) detailed fraction",
- "regex": "^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?((Z|(\+|\-)\d{2}:\d{2}))$",
- "example": "2005-11-12T12:01:42.123+01:00"
- },
- "time": {
- "description": "time (based on RFC3339 5.6) detailed fraction",
- "regex": "^\d{2}:\d{2}:\d{2}(\.\d{3})?((Z|(\+|\-)\d{2}:\d{2}))$",
- "example": "12:01:42.123+01:00"
- },
- "date": {
- "description": "date (RFC3339 5.6)",
- "regex": "^\d{4}-\d{2}-\d{2}$",
- "example": "2005-11-12"
- },
- "uri": {
- "description": "uri with schema http(s) or w/o Authority",
- "regex": "^(https?:(\/\/([a-z0-9\-._~%]+|\[[a-f0-9:.]+\])(:[0-9]+)?))?(\/[a-z0-9\-._~%!@include("assets/formats.json")'()*+,;=:@]+)*\/?(\?[a-z0-9\-._~%!@include("assets/formats.json")'()*+,;=:@\/?]*)?(\#[a-z0-9\-._~%!@include("assets/formats.json")'()*+,;=:@\/?]*)?$",
- "example": "http://www.example.com/aDocument?foo#bar"
- },
- "ical": {
- "description":"iCal format defined in https://tools.ietf.org/html/rfc5545",
- "regex": "^BEGIN:VCALENDAR[\S\s]+END:VCALENDAR$",
- "example": "BEGIN:VCALENDAR END:VCALENDAR"
- }
-}
-
- It is also allowed to define a dedicated regular expression pattern as format on property definition level.
+ "uuid": {
+ "description": "unique identifier",
+ "regex": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+ "example": "388d3a25-663b-11e3-949a-0800200c9a66"
+ },
+ "geoposition": {
+ "description": "latitude followed by longitude and altitude in meters separated by ';'",
+ "regex": "^[-+]?[0-9]*\.?[0-9]*;[-+]?[0-9]*\.?[0-9]*;[-+]?[0-9]*\.?[0-9]*$",
+ "example": "37.772323;-122.214897;0"
+ },
+ "e164telephonenumber": {
+ "description": "E.164 encoded Telephone number",
+ "regex": "^\+?\d{4,23}$",
+ "example": "+49536190"
+ },
+ "macaddress": {
+ "description": "device mac address",
+ "regex": "^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$",
+ "example": "a3:3E:ff:e3:01:fe"
+ },
+ "rgba": {
+ "description": "rgba color with alpha",
+ "regex": "^rgba\((\d{1,3}),\s*(\d{1,3}),\s*(\d{1,3})(?:,\s*(\d(?:\.\d+)?))?\)$",
+ "example": "rgba(25,9,19,0.4)"
+ },
+ "language": {
+ "description": "HTTP1.1 compatible language tag",
+ "regex": "^(\w{2})(-\w*)?$",
+ "example": "en-gb"
+ },
+ "servicecategory": {
+ "description": "plain string category name",
+ "regex": "^[a-z]*$",
+ "example": "car"
+ },
+ "duration": {
+ "description": "iso8601 duration",
+ "regex": "^P\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$",
+ "example": "P0003-06-04T12:30:05"
+ },
+ "temperatureUnit": {
+ "description": "temperature measurement unit",
+ "regex": "^[KCF]{1}$",
+ "example": "C"
+ },
+ "distanceUnit": {
+ "description": "distance unit",
+ "regex": "^mi|km|yd|m|ft$",
+ "example": "km"
+ },
+ "pressureUnit": {
+ "description": "pressure measurement unit",
+ "regex": "^bar|psi|kPa$",
+ "example": "bar"
+ },
+ "volumeUnit": {
+ "description": "volume measurement unit (ul = microliter, us.dry.gal = dry US gallon, us.liq.gal = liquid US gallon, imp.gal = imperial gallon)",
+ "regex": "^l|ml|ul|us.liq.gal|us.dry.gal|imp.gal$",
+ "example": "ml"
+ },
+ "consumptionUnit": {
+ "description": "consumption measurement unit (fluid, gas, electric)",
+ "regex": "^l/100km|l/h|km/l|mpgUS|mpgUK|g/h|kg/100km|km/kg|kg/h|m3/100km|km/m3|m3/h|miles/lbs|lbs/h|miles/yard3|yard3/h|miles/kg|miles/m3|kWh/100km|km/kWh|kWh/100miles|miles/kWh|kW|Ws|miles/gal_eqUS$",
+ "example": "l/h"
+ },
+ "weightUnit": {
+ "description": "consumption measurement unit (fluid, gas, electric)",
+ "regex": "^t|kg|g|mg|lbs$",
+ "example": "kg"
+ },
+ "speedUnit": {
+ "description": "speed unit",
+ "regex": "^kmh|mph|m/s$",
+ "example": "kmh"
+ },
+ "timeFormat": {
+ "description": "the time format for clocks",
+ "regex": "^12h|24h$",
+ "example": "12h"
+ },
+ "dateFormat": {
+ "description": "date format",
+ "regex": "^ddmmyyyy|mmddyyyy|yyyymmdd$",
+ "example": "mmddyyyy"
+ },
+ "date-time": {
+ "description": "date-time (based on RFC3339 5.6) detailed fraction",
+ "regex": "^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?((Z|(\+|\-)\d{2}:\d{2}))$",
+ "example": "2005-11-12T12:01:42.123+01:00"
+ },
+ "time": {
+ "description": "time (based on RFC3339 5.6) detailed fraction",
+ "regex": "^\d{2}:\d{2}:\d{2}(\.\d{3})?((Z|(\+|\-)\d{2}:\d{2}))$",
+ "example": "12:01:42.123+01:00"
+ },
+ "date": {
+ "description": "date (RFC3339 5.6)",
+ "regex": "^\d{4}-\d{2}-\d{2}$",
+ "example": "2005-11-12"
+ },
+ "uri": {
+ "description": "uri with schema http(s) or w/o Authority",
+ "regex": "(https?:(\/\/([a-z0-9\-._~%]+|\[[a-f0-9:.]+\])(:[0-9]+)?))?(\/[a-zA-Z0-9\-._~%!&\$'()*+,;=:@]+)*\/?(\?[a-zA-Z0-9\-._~%!&\$'()*+,;=:@\/?]*)?(\#[a-zA-Z0-9\-._~%!&\$'()*+,;=:@\/?]*)?",
+ "example": "http://www.example.com/aDocument?foo#bar"
+ },
+ "ical": {
+ "description":"iCal format defined in https://tools.ietf.org/html/rfc5545",
+ "regex": "^BEGIN:VCALENDAR[\S\s]+END:VCALENDAR$",
+ "example": "BEGIN:VCALENDAR END:VCALENDAR"
+ },
+ "point2D": {
+ "description": "The coordinates of a point, where “0;0” is the upper left corner of the coordinate system.",
+ "regex": "^\d{6};\d{6}$",
+ "example": "300;200"
+ },
+ "rectangle2D": {
+ "description": "The description of a rectangle. The first two values describe the upper left corner of the rectangle, where “0;0” is the upper left corner of the coordinate system. Value 3 describes the width, value 4 the height of the rectangle.",
+ "regex": "^\d{6};\d{6};\d{6};\d{6}$",
+ "example": "0;0;1280;640"
+ }
+ }
+
It is also allowed to define a dedicated regular expression pattern as format on property definition level.
number vs integer
JSON does not allow non-numbers like NaN, nor does it make any distinction between integer and floating point. If the format integer is used in this document or the object definitions, the meaning is that a service will send and expect integer values. The parsing must be compatible with parsing a number into an integer, because there is no distinction during transfer (on the wire). If the format is defined as number, neither client nor service may parse it as an integer.
Language tags
@@ -2258,27 +2244,28 @@
Service category names
Services are categorized to let clients register and find similar services. Services are found via GETon root level, using the query parameter ?servicecategory=<name>, wherein <name> is one of the following category names:
[
- "addresses", // address related information
- "auth", // authentication and authorization
- "car", // vehicle states, vehicle configurations
- "cdn", // static content
- "charging", // charging management
- "ev", // electric vehicle information, states and configurations
- "search", // dedicated searches that aggregate general searching
- "hybrid", // HEV related information, states and configurations
- "map", // digital map
- "maprendering", // visual maps
- "inputdevices", // input devices like optical sensors, hardkeys, capacitive keys
- "media", // media related like rendering, queues(collections)
- "medialibrary", // services hosting media items like tracks, albums or videos
- "mixer", // audio management
- "navigation" // route calculation and navigation general
- "communication", // phone, messaging etc.
- "system", // system related, like performance, window management or registration
- "radio", // radio
- "speech" // speech dialogs
-]
-
+ "addresses", // address related information
+ "auth", // authentication and authorization
+ "car", // vehicle states, vehicle configurations
+ "cdn", // static content
+ "charging", // charging management
+ "ev", // electric vehicle information, states and configurations
+ "search", // dedicated searches that aggregate general searching
+ "hybrid", // HEV related information, states and configurations
+ "map", // digital map
+ "maprendering", // visual maps
+ "inputdevices", // input devices like optical sensors, hardkeys, capacitive keys
+ "media", // media related like rendering, queues(collections)
+ "medialibrary", // services hosting media items like tracks, albums or videos
+ "mixer", // audio management
+ "navigation" // route calculation and navigation general
+ "communication", // phone, messaging etc.
+ "system", // system related, like performance, window management or registration
+ "radio", // radio
+ "speech", // speech dialogs
+ "swdl" // all things related to software download
+ ]
+ Language
Every request may contain an Accept-Language Header field, which allows the client to let the service know about the accepted languages (cmp. RFC2616#14.4).
In case of language depended content (e.g. city names), the service shall add the Content-Language Header to the response representing the actual language used to generate the content.
Namespaces
Namespaces are, themselves, uuids. While the UUID specification gives example UUIDs for namespaces corresponding to fully qualified domain names (DNS), URLs, ISO OIDs, and X.500 DNs, any UUID can be used as the namespace when generating Version 5 uuids. Thus, nesting of namespaces is possible. A good practice is to use <service> and <resource> names for namespacing.
Version 4 (random)
-Version 4 UUIDs use a scheme relying only on random number generations. This algorithm sets the version number (4 bits) as well as two reserved bits. All other bits (the remaining 122 bits) are set using a random or pseudorandom data source. Version 4 UUIDs have the form
+Version 4 UUIDs use a scheme relying only on random number generations. This algorithm sets the version number (4 bits) as well as two reserved bits. All other bits (the remaining 122 bits) are set using a random or pseudorandom data source. Version 4 UUIDs have the form
xxxxxxxx-xxxx-4xxx-Yxxx-xxxxxxxxxxxx
where x is any hexadecimal digit and Y is one of 8, 9, A or B.
uniqueness criteria
Interface design patterns
Settings
-When ever a service needs general settings which also may include a reset to factory defaults, a settingsresource is used. The individual settings are evaluated by their name and value/state.
When ever a service needs general settings which also may include a reset to factory defaults, a settings resource is used. The individual settings are evaluated by their name and value/state.
Naturally delayed responses
There are cases, where a delayed and incremental results to a query can generally be expected. In case of Bluetooth device discovery for example a server side device scan has to be triggered. In these cases an immediate response to a GET request is neither possible nor practical for client side usage. The general pattern for these kind of applications/services should follow the principle :
A POST request on resource level is used to create a new object. The client can subscribe to on change events for the newly created object or poll (GET) it continuously. The newly created object will change over time until completion. This pattern is applicable to:
Virtual collection content
There are cases in which an endpoint needs to present a list of items to strictly follow REST principles and/or to allow a convenient access to its information despite a lack of knowledge about these items. In particular, cases where a list is dynamically appended or prepended based on a selection made in this list by the holding object itself. An example for these use cases is a media renderer for bluetooth media - the next bluetooth track is only available once playback of this track has already started.
The list will contain 0,1 or 2 virtual elements that are accessible but will just have a valid id and uri for as long as they are not pointed at. These elements will be placed at either end of the list. Once the element is referenced / pointed to by the client, an atomic action is executed:
-
-
- making the virtual element non-virtual -
- creating a new virtual element -
- extend the list +
- making the virtual element non-virtual +
- creating a new virtual element +
- extend the list
Only on success, an update on the list and the reference is sent.
Registration
response:
HTTP/1.1 201 Created
-Content-Type: application/json; charset=utf-8
-Location: <URI of created service>
-
-
-{
- "status": "ok"
-}
-Unregistration
+ Content-Type: application/json; charset=utf-8 + Location: <URI of created service> + + + { + "status": "ok" + } +Unregistration
Unregistration is only allowed on id level, i.e. by sending DELETE. DELETE requests on other accessing paths will result in a status code 400 Bad request
request:
DELETE /<service_uuid> HTTP/1.1
-Host: 127.0.0.1:1337
-Accept: application/json;q=0.8
-response:
+ Host: 127.0.0.1:1337 + Accept: application/json;q=0.8 +response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8