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.

Protocol Requirements & Limitations

Although the HTTP transport doesn't perform any transport level client interaction, it does place some specific requirements and limitations on protocol implementations:

· A protocol service MUST support non cookie based session tracking

· A protocol service MUST NOT require custom HTTP headers

· A protocol service MUST NOT expect POST content types other than text/plain

· A protocol service MUST NOT return content types other than text/plain

· A protocol service MUST support CORS

· A protocol service MUST provide authentication mechanisms outside of those provided by HTTP

Most of these limitations are present to support the widest range of clients, especially browser platforms, possible. Versions of IE earlier than IE 10 have severe limitations placed on their ability to access web services from origins other than the one that served the original web content.

Direct Client Protocol Services

The direct client protocol is delivered over HTTP via a group of services that allow client authentication, sending requests, and polling for events and responses.

Client Session Management

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:

Starting a Session

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

{
  "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

{
  "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

{
  "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.

Making Direct Protocol Requests

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.

Receiving Responses, Errors, and Events

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.

{
  "messages":
  [
    {
      MESSAGE_1_CONTENTS
    },
    {
      MESSAGE_2_CONTENTS
    },
    …
  ]
}