This document, the Gen2 TRANSPORT specification, describes the Gen2 transport protocols, and the mapping of the message layer on these transports. The companion specification Gen2 CORE describes the messaging layer.
This is required.
This document describes the transport bindings of the Vehicle Service Interface. The split between transport bindings and messaging layer specifications improves readability and simplify extending Gen2 to further transports in the future. The Gen2 supports multiple transport bindings, namely HTTPS and secure WebSockets.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. The key words MAY, MUST, and SHALL are to be interpreted as described in [RFC2119].
The acronym 'Gen2' is used to refer to this document, the 'Gen2' specification. The acronym 'VSS' is used to refer to the 'Vehicle Signal Specification' which is defined by the GENIVI Alliance. The term 'WebSocket' when used in this document, is as defined in the W3C WebSocket API and the WebSocket Protocol.
This chapter defines features that SHALL be common for all transport protocols.
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]. However, some status codes are generally not expected by the client, those codes are not shown in the table below. If received by a client, they can be ignored.
| Code | Name | Implication | Client-side treatment |
|---|---|---|---|
| 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. |
| 300 | Multiple Choices | Used if multiple services match the request criteria (service registry only) | Client has to select and re-request |
| 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 |
| 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. |
| 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 /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 |
| 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. |
| 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. |
| 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. |
The payload SHALL have JSON format. See for the payload format of the messages for the different transport protocols.
Clients must provide a token to the server in order to verify that it is correctly authorized for the service it requests (c.f. CORE document).Tokens are integrated in HTTP requests in the Authorization header. For WebSockets requests an optional authorization property in the payload can be used.
The transport protocols supported are the secure versions of HTTP and WebSockets. Further transport protocols may be supported in future versions of this specification.
The message data components described in the CORE document are in the first hand mapped to required HTTP parameters, and only when there is no appropriate mapping it is mapped to the payload. The subscribe/unsubscribe messages are not supported by this transport protocol.
Example:
Request:
GET Vehicle/Drivetrain/InternalCombustionEngine/RPM 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
{
"value": 2372,}
"timestamp": 1489985044000
JWT tokens will be sent in the Authorization header, following with term Bearer and a space character.
The following example assumes eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds is the actual token:
GET /Vehicle/Drivetrain/InternalCombustionEngine/RPM/ HTTP/1.1
Host: 127.0.0.1:1337
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds
Example:
Request:
GET Vehicle/Drivetrain/FuelSystem?$spec=0 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
{
"metadata": {"FuelSystem":{"type":"branch","description":"Fuel system data.","children":{"HybridType, ... }}}}
"timestamp": 1489985044000
Example:
POST /Vehicle/Drivetrain/Transmission/PerformanceMode HTTP/1.1
Host: 127.0.0.1:9000
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
{
"value": "sport",}
"timestamp": 1489985044000}
JWT tokens will be sent in the Authorization header, following with term Bearer and a space character.
The following example assumes eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds is the actual token:
POST /Vehicle/Drivetrain/Transmission/PerformanceMode/ HTTP/1.1
Host: 127.0.0.1:1337
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UifQ.xuEv8qrfXu424LZk8bVgr9MQJUIrp1rHcPyZw_KSsds
{
"value": "sport",
}
As the WebSocket protocol does not implicitly provide a logical association between the request and response messages described here a key-value pair with the keyname "requestId" is added to the data components described in the CORE document. As the WebSockets protocol neither specifies a set of explicit methods, another key-value pair with the keyname "action" is also added. See for the declaration of these new key-value pairs. All data components are mapped to the payload.
Example:
Request:
{
"action": "getRequest",}
"path": "Vehicle/Drivetrain/InternalCombustionEngine/RPM",
"requestId": "8756"
"action": "getSuccessResponse",}
"requestId": "8756",
"value": 2372,
"timestamp": 1489985044000
Example:
Request:
{
"action": "getRequest",}
"path": "Vehicle/Drivetrain/InternalCombustionEngine/RPM",
"authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds"
"requestId": "8657"
"action": "getSuccessResponse",}
"requestId": "8657",
"value": 2372,
"timestamp": 1489985044000
Example:
Request:
{
"action": "getRequest",}
"path": "Vehicle/Drivetrain/FuelSystem?$spec=0",
"requestId": "5687"
"action": "getSuccessResponse",}
"requestId": "5687",
"metadata": {"FuelSystem":{"type":"branch","description":"Fuel system data.","children":{"HybridType, ... }}}
"timestamp": 1489985044000
Example:
Request:
{
"action": "setRequest",}
"path": "Vehicle/Drivetrain/Transmission/PerformanceMode",
"value": "sport",
"requestId": "5687"
"action": "setSuccessResponse",}
"requestId": "5687",
"timestamp": 1489985044000
Example:
Request:
{
"action": "setRequest",}
"path": "Vehicle/Drivetrain/Transmission/PerformanceMode",
"value": "sport",
"authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds"
"requestId": "5687"
"action": "setSuccessResponse",}
"requestId": "5687",
"timestamp": 1489985044000
Example:
Request:
{
"action": "subscribeRequest",}
"path": "Vehicle/Drivetrain/FuelSystem/Level",
"filter": "$intervalEQ2"
"requestId": "6578"
"action": "subscribeSuccessResponse",
"subscriptionId": "12345",
"requestId": "6578",
"timestamp": 1489985044000
"action": "subscriptionNotification",
"subscriptionId": "12345",
"value": 50,
"timestamp": 1489985044000
Example:
Request:
{
"action": "subscribeRequest",}
"path": "Vehicle/Drivetrain/FuelSystem/Level",
"filter": "$rangeGT5AND$rangeLT10"
"authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1...Zw_KSsds"
"requestId": "6578"
"action": "subscribeSuccessResponse",
"subscriptionId": "12345",
"requestId": "6578",
"timestamp": 1489985044000
"action": "subscriptionNotification",
"subscriptionId": "12345",
"value": 50,
"timestamp": 1489985044000
Example:
Request:
{
"action": "unsubscribeRequest",}
"subscriptionId": "12345",
"requestId": "5786"
"action": "unsubscribeSuccessResponse",}
"subscriptionId": "12345",
"requestId": "5786",
"timestamp": 1489985044000
The payload that is sent over the supported transport protocols SHALL use the JSON definitions in this appendix, unless otherwise specified in the Gen2 TRANSPORT specification.
Diagram showing xxx.
RFC2119: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
RFC2616: Hypertext Transfer Protocol -- HTTP/1.1. Fielding, et al. IETF. June 1999. URL: https://tools.ietf.org/html/rfc2616