This file details the HTTP REST Binding which uses HTTPS as Transport protocol layer and JSON as Data Format protocol layer.
The Local Agent acts as a HTTP client and the Remote Agent as a HTTP server. Each GP SERAM Message may be transmitted in exactly one HTTP message.
The formal API specification of the HTTP REST Binding is provided in OpenAPI format. This specification file may be used to generate code skeleton as shown in maven project file (pom.xml).
The HTTP REST Binding SHALL comply with:
- RFC2818 – HTTP Over TLS
- RFC6265 – HTTP State Management Mechanism
- RFC7230 – Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
- RFC7231 – Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
- RFC7232 – Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests
- RFC7234 – Hypertext Transfer Protocol (HTTP/1.1): Caching
HTTP messages are attached with a Managment Session based on the sessionId. The sessionId is explicitly inserted in each HTTP request and implicitly determined for HTTP response based on the client-server paradigm of the HTTP protocol.
Implementors MAY uses another HTTP mechanism to reinforce the HTTP session (e.g. HTTP cookies). A Local Agent SHOULD support HTTP cookies as defined in RFC6265.
Two endpoints are defined: one to make the Handshake Step and the second to makes the Command Exchange Step.
| Endpoint | Description |
|---|---|
| /handshake | Handshake Step |
| /remoteManagement | Command Exchange Step |
The Handshake Command Message SHALL be mapped to a HTTP POST request and the associated Handshake Response Message to the associated HTTP Response.
JSON schema for the HTTP request and response during Handshake Step SHALL fullfill the GP SERAM OpenAPI specification.
The Order Message SHALL be mapped to an HTTP response and the associated Report Message to the next HTTP Request.
The JSON schema for the HTTP request and response during Command Exchange Step SHALL fullfill the GP SERAM OpenAPI specification.
To allow the Remote Agent to send Order Messages to the Local Agent, an HTTP polling is used as server-push mechanisms.
During HTTP polling, some void HTTP messages MAY be used. A void HTTP message is any Order or Report Message which doesn’t carry any Command or Response, and which role is to maintain the communication channel between the Remote Agent and the Local Agent. The first HTTP request to the Remote Agent is always a void HTTP message.
The Local Agent SHALL uses HTTP polling whenever awaiting a Order Message. It SHALL NOT use HTTP polling whenever it’s processing the previous Order Message unless it doesn’t require any Response.
The Remote Agent may fine-tune the HTTP polling by controlling the delay between an HTTP response and the next HTTP request. If the Remote Agent doesn’t specify any delay, the Local Agent SHALL make a pause of 1 second before sending the next HTTP request. The Remote Agent MAY used a value of 0 to deactivate the delay.
As describes in RFC6202, the Remote Agent MAY use HTTP long polling mechanism and wait a certain period of time before sending the void HTTP response. Remote Agent SHOULD NOT used period of time beyond 30 seconds and Local Agent SHOULD at least support latency of 30 seconds between HTTP request and HTTP response.
The Local Agent and the Remote Agent relies on HTTP protocol to their exchanges. Most of the transmission errors will be transparently resumed by the TCP (Transmission Control Protocol) end-to-end stack.
Nevertheless, some errors are unrecoverable at TCP level. This section lists the rules a Local Agent and Remote Agent shall follow to enforce the Message delivery or error detection.
Errors may result in a failure on each level of the exchanges:
-
the Local Agent
-
the Remote Agent
-
the Device
-
the network
If the HTTPS connection is prematurely closed, the Local Agent SHOULD immediately try to re-establish the HTTPS connection with the Remote Agent.
If the Local Agent could not establish an HTTPS connection or send an HTTP request to the Remote Agent, it SHOULD retry during 5 minutes at the most.
If the Local Agent doesn’t receive an HTTP response within a 40 seconds delay from the Remote Agent, it SHOULD close the current HTTPS connection and try to re-establish a new one.
If a Remote Agent could not send an HTTP response to a Local Agent within a 30 seconds delay, it SHALL close the current HTTPS connection and SHOULD await the Local Agent reconnection.
A Remote Agent SHOULD consider having lost a Local Agent after a 5-minute delay.