This chapter provides a detailed specification for the HTTP Transport and describes how clients use the transport to communicate with HIS. It contains these sections:·
...
...
Transport Overview
The HTTP transport is unique in that the separation between transport and protocol is more fluid than for the other transports. A protocol is implemented by a set of RESTful web services registered under a common base URI prefix. A client can determine if HIS supports a particular protocol over the HTTP Transport by issuing an OPTIONS request to the given URI prefix.
...
To use the direct client protocol over HTTP, a client must first initiate a new session with HIS using the Session Management service. Once a client has an active session, it can send requests and poll for responses and events. When a client is finished using the direct protocol, it should explicitly close its session. Sessions will automatically be removed if no request is received or no event polling occurs for greater than the session timeout, which is configurable. The Session Management service can be accessed with the following URL:
http://[server_name]:[server_port]/sessions
The following diagram illustrates the typically lifecycle of clients using the Direct Client Protocol over HTTP:
...
A new session can be created by POSTing a startSession message to the Session Management service. The client identifies itself using the client JSON structure. The name property is required and is used for logging and management purposes. The id property is optional. If no id property is provided, a unique identifier will be generated and returned to the client.
Request
| Code Block |
|---|
{
| ||
{ "messageType": "startSession", |
...
"client": |
...
{
{ "id": "[client_id]", |
...
"name": "[client_name]" |
...
} |
...
} |
The server will respond with a JSON structure that includes the client identifier. If the client provided an id as part of the startSession message, the provided id is returned. Otherwise, a new id is generated and returned.
Response
| Code Block | ||
|---|---|---|
| ||
{ |
...
"id": "[client_id]" |
...
} |
Ending a Session
An existing session can be closed by POSTing an endSession message to the Session Management service. The client identifies itself using the client JSON structure. The server will gracefully end the session with the matching client id.
Request
| Code Block | ||
|---|---|---|
| ||
{ |
...
"messageType": "endSession", |
...
"client": |
...
{
{ "id": "[client_id]", |
...
"name": "[client_name]" |
...
} |
...
} |
The server will respond with an HTTP 200 OK status code once the session has been cleaned up. If the session was not found, the server will respond with an HTTP 404 Not Found status code.
...
Once a client has an active session, it can begin sending Direct Protocol requests to HIS. To send a request, the client POSTs the request JSON to the Request Processor service and provides its identifier. The service can be accessed using the following URL:
http://[server_name]:[server_port]/direct/processRequest?clientId=[client_id]
The contents of the POSTed JSON are delivered as-is to the direct protocol handler for processing. The server responds with an HTTP 200 OK status code if the message is accepted for processing. It is important to note that the HTTP response does not indicate that the request was completed successfully, but only indicates that the request was accepted and queued for processing. Any response message for the request must be retrieved via the Message Polling service.
...
As the client interacts with HIS, it needs to retrieve the responses to its requests and any events that might arise. The client must poll for new messages using the Message Polling service. The service can be accessed using the following URL:
http://[server_name]:[server_port]/direct/getMessages?clientId=[client_id]
To reduce the latency in receiving messages and the overall network traffic, the Message Polling service employs long polling. The service will not provide a response to the getMessages request until at least one message is available or some timeout has passed. Any messages that become available between client requests will be queued and delivered during the next polling cycle. Received messages should be processed in the background, allowing the client to immediately start the next polling cycle.
Messages returned from the Message Polling service request are wrapped in a JSON structure and will always be listed in the order they were generated.
| Code Block |
|---|
{
| ||
{ "messages": |
...
[
{
[ { MESSAGE_1_CONTENTS |
...
}, |
...
{
{ MESSAGE_2_CONTENTS |
...
}, |
...
…
]
… ] } |