This chapter provides a detailed specification for the Direct Client Protocol and describes how the protocol is implemented on each Transport. It contains these sections:

Protocol Overview

The direct client protocol is designed to expose the base Network Core API to the client. Clients using this protocol are capable of accessing any and all features provided by the underlying Network Services and Resources.

The cost of this flexibility is the increased complexity of client code necessary to implement the protocol. Clients are responsible for managing the binding of Network Services and Resources. Clients are also required to be aware of the API details of each Network Service and Resource they use, as well as the processes around using those APIs.

Core Messages

There are 4 types of core messages: Core Request, Core Response, Core Event, and Core Error. The client initiates an action by sending a Core Request. The Network Core will either generate a Core Response or Error in reply to the request depending on the result. The Network Core may also generate Core Events as a result of processing a Core Request or in response to other events within the HIS container.

The exact format and contents of these messages depends on which transport carries them. However, regardless of transport, each message class will always include certain information:

Core Request

· Request Id – Uniquely identifies this request from all others

· Request Type – Determines the type of request being made

Core Response

· Request Id – Uniquely identifies the original request that produced this response

· Response Type – Matches the original request type

· Result – Indicates success or failure of the original request

· Response Data – Responses which carry data will have a dedicated section to contain it

· Error Information – If the request was unsuccessful, information about the failure will be provided

Core Event

· Event Name – Identifies the type of event that occurred

· Event Data – Events which carry data will have a dedicated section to contain it

Core Error

· Error Type – The type of error that occurred

· Error Information – Any information about the error condition will be provided

Service and Resource Messages

The messages delivered to a service or resource and the messages they produce in response or raise as events follow the same general guidelines as core messages. However, service messages will always carry the unique identifier for the target service and resource messages will always carry the unique identifiers for both the parent service and the target resource.

Message Formats

This section outlines the general format for each type of message used by the direct client protocol. For details on specific messages, including usage and example contents, see appropriate section below.

Base Message Format

All messages sent and received over the socket transport are packaged as JSON structures and delivered in the message content section of the socket transport message frame. The class of message is identified by the "messageType" property of the top-level JSON object:

{
  "messageType": "[message-class]"
}

There are 12 message classes representing requests, responses, events, and errors for services, resources, and the network core itself.

coreRequest
coreResponse
coreEvent
coreError
serviceRequest
serviceResponse
serviceEvent
serviceError
resourceRequest
resourceResponse
resourceEvent
resourceError

Each message class builds on the base message format adding additional properties to the JSON object. Some properties may be objects themselves with internal properties.

Core Request

All core request messages include the additional properties requestId and command. The request id should be unique among all requests so should be a GUID or UUID. The protocol doesn't require a particular format for the identifier. It is treated as a text value for reference and comparison without further processing.

{
  "messageType": "coreRequest",
  "requestId": "[request-id]",
  "command": "[request-name]"
}

Core Response

A core request can generate one of two types of responses: success or failure. A successful response indicates that the request was completed without issue and any data associated with the request is provided in the response message. A failure response indicates that the request could not be completed given the information provided in the request. A failure response differs from an error in that the failure state is normal and recoverable, where as an error is abnormal and is often times unrecoverable. The success or failure of a request is provided in the "result" property of the response message.

Success Response

{
  "messageType": "coreResponse",
  "requestId": "[original-request-id]",
  "command": "[original-request-command]",
  "result": "success"
}

Failure Response

Core Event

A core event is generated in response to some asynchronous activity within the HIS container. It may be related to the processing of a previously issued request, or may be completely unsolicited. Core events carry the name of the event and information related to the event if available. If no additional information is provided with the event, the "event" property is typically not present. For details of the "event" property's contents see the description for each individual event below.

Core Error

A core error message represents a serious error state that renders the requested activity, the client connection, or even the HIS container unrecoverable. Errors are usually related to malformed requests or other issues encountered while processing messages. If the original request that produced the error can be determined and the request's identifier can be retrieved, it is provided in the "requestId" property of the error message.

Service Request

A service request consists of an outer shell, or envelope, that identifies the destination service and an inner payload with the details of the request in a service specific format. The "serviceId" property defines the target of the request.

Service Response

Unlike a core response, a service response message does not define success or failure in the outer envelope. The details of the response, including disposition, are contained within the inner payload.

Service Event

Service events follow the same general structure as core events with the addition of the "serviceId" property to denote the service that generated the event and the event name is moved into the event contents.

Service Error

As with a core error message, a service error represents a serious error state that is likely not recoverable and may result in the automatic unbinding of the client from the service.

Resource Request

Like a service request, a resource request consists of an outer shell, or envelope. The envelope identifies the parent service and destination resource. The inner payload provides the details of the request in a service specific format. The "serviceId" property defines the parent service and the "resourceId" property selects the target resource of the request.

Resource Response

Unlike a core response, a resource response message does not define success or failure in the outer envelope. The details of the response, including disposition, are contained within the inner payload.

Resource Event

Resource events follow the same structure as service events with the addition of the "resourceId" property to denote the resource that generated the event.

Resource Error

As with a core error message, a resource error represents a serious error state that is likely not recoverable and may result in the automatic unbinding of the client from the resource.

Core Requests and Responses

There are XX core commands supported by the direct client protocol. This section provides example content and flows for each request and the possible responses that might be generated.

authenticate (Obsolete)

Socket Transport (Obsolete)

The real-time and bi-directional nature of the Socket Transport lends itself well to the direct client protocol. After the client completes the transport's handshake phase, it can begin sending core requests and receiving core events and responses. The client can also begin binding the services and resources it requires.

As per the Socket Transport specification, the client session begins with the client opening a socket to HIS and completing the handshake phase. Once the handshake is processed, the client begins to send requests to HIS. Responses, events, and errors will be sent to the client as they are generated by HIS. It is highly recommended that the client leverage a multithreaded processing model; separating the receiving of messages from performing in response to them.

HTTP Transport

The HTTP Transport allows for quick development of client applications, but doesn't offer the flexibility or performance of the Socket Transport.