REST Edge Specification
Direct Health Messaging via Representational State Transfer over HTTP
Status of this Specification
This specification is in Draft state.
IPR Statement
By contributing to this specification, all contributors warrant that all applicable patient or other intellectual policy rights have been disclosed and that any of which contributors are aware of will be disclosed in accordance with the Direct project IPR Policy.
Abstract
This specification provides a mapping of the Direct Abstract Model to Representational State Transfer (REST) HTTP resources. It covers both the "Health Message Source System to HISP" and "HISP to Health Message Destination System" User Stories.
Table of Contents
Introduction
The original Concrete Implementation Group defined a REST Specification to support complete end to end health messaging, including messaging between HISPs. This specification is a subset of that specification and only focuses on the interaction between an edge Source/Destination system and a HISP with a focus on a simple API for client systems.
Purpose
The purpose of this document is to define a standard set of REST APIs that may be exposed by a compliant HISP for consumption by and edge client. Client software written to utilize services based on this specification should be able to integrate with any HISP that exposes REST APIs based on this specification.
The Direct Project has defined specifications for messaging between HISPs and source/destination messaging using other protocols, particularly email protocols based on SMTP, POP3, and IMAP. Existing EMR vendors with software based on web technologies have expressed interest in using web technologies to achieve messaging with a HISP system. The most common user stories for sending and receiving Direct messages are addressed using REST web service calls.
This specification does not dictate the contents of messages other than to reference the relevant specifications.
This specification does not dictate the mechanism used for message delivery notification (MDN). MDN is assumed to happen in the regular message stream using referenced specifications.
Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."
Synopsis
A Health Information Service Provider (HISP) is an organization that provides the RESTful services described in this document.
This specification defines a uniform set of REST resources provided by each HISP:
| Resource |
Resource Description |
| Messages |
Resource for retrieving messages for addresses associated with a user or posting a new message |
| Messages/{message-id}/Status |
The status of a message resource identified by the {message-id} value |
These resources are mapped to a common set of relative URIs and HTTP methods on those URIs with well defined semantics as defined in this document.
| Resource |
Method |
Headers |
Representation |
| Messages |
GET |
Accept: application/atom+xml |
An Atom feed of messages where each entry element contains an link element with a rel "alternate" attribute and an href attribute that contains the URI of the individual message |
| Messages |
POST |
Content-Type: message/rfc822 |
A health content container. |
| Messages |
GET |
Accept: message/rfc822 |
A health content container representing the message at the specified resource |
| Messages/{message-id}/Status |
GET |
Accept: text/plain |
Returns a representation of the indicated message status |
| Messages/{message-id}/Status |
PUT |
Content-Type: text/plain |
Updates the selected message status. |
Health data security and trust are provided by using S/MIME to sign and encrypt RFC 5322 Internet Message Format documents such that only authorized persons, and their explicitly authorized delegates may view messages, and such that they may verify the provenance of each message. Refer to the Content Security for Simple Health Transport Specification for information on the use of S/MIME and other security requirements.
Push Optimization
While it's certainly possible for a client to perform all message retrieval tasks explicitly by polling the HISP for messages, a higher volume system managing thousands of addresses may require more efficient messaging. This specification also provides for push connectivity from HISP to destination by having the destination system expose the POST interface on the Messages resource. A HISP MAY choose to push messages to a destination endpoint that supports the Messages endpoint. In that case all communication is handled via a single REST interface, the POST Messages resource.
Terminology
The terminology adopted in the Direct Abstract Model, Content Container Specification, Addressing Specification, and Content Security for Simple Health Transport Specification is also adopted in this document.
URIs, Resources, and Protocol Operations
Base URI
The hisp-domain-name must be a DNS name resolving to the HISP server exposing the REST API. There is not necessarily a relationship between the hisp-domain-name and the health domain name of the source or recipient addresses for messaging.
base-uri = "https://" hisp-domain-name "/direct/" api-version
api-version = "v1"
The api-version MAY be incremented in later versions of this specification. All URIs using the api-version of v1 MUST correspond in format and semantics to this specification.
Non-normative examples of the Base URI include:
https://direct.nelsoncardiology.org/direct/v1 https://direct.bigidnco.example.com/direct/v1
Messages Resource
messages-uri = base-uri "/messages"
The Messages Resource represents per user retrievable messages on the HISP.
Messages List Operation
An authenticated and authorized GET Request to the messages-uri SHALL provide a list of messages sent to all Health Internet Address belonging to that authenticated user.
The following protocol operations MUST be provided by implementations of this specification in response to a GET Request to messages-uri:
| Accept |
Conditions |
Response Status |
Response Content |
| application/atom+xml |
Authenticated and authorized request |
200 |
A Messages List representation formated as described below containing references to the NEW individual Message resources sent to the Health Internet Address and available for access |
| Any |
Not authenticated |
401 |
None |
Implementations MUST handle authenticated but not authorized requests. Clients SHOULD be prepared to handle status codes in the 400 range or empty documents. Implementations MAY provide other representations in response to different Accept header values.
The behavior of most systems will be to return all messages with the message status of NEW. Once a message has been retrieve through the Message resource, it's status should be updated to ACK or NAK through the Message Status resource. Once it's status has been updated to something other than NEW it will no longer show up in the list returned by the Messages resource.
Messages List Atom Representation
The Atom representation of a Messages List MUST conform to the following constraints:
- The Atom feed MUST be a valid Atom feed, corresponding to RFC 4287
- The Atom feed MUST contain one entry element for each listed Message resource
- The entry element MUST contain a link element with a rel attribute of value "alternate" and an href attribute providing the URI of the listed Message resource
Implementations MAY provide additional information in the Messages List Atom representation.
Message Create Operation
An authenticated and authorized POST Request to the messages-uri SHALL create a message resource.
The following protocol operations MUST be provided by implementations of this specification in response to a POST Request to messages-uri:
| Content-Type |
Conditions |
Response Status |
Response Content |
| message/822, non-signed and encrypted body |
An authenticated and edge role authorized user who is the message sender, HISP has created the message, either locally or through synchronous remote creation |
201 |
Location header providing the message-uri of the created resource |
| message/822, non-signed and encrypted body |
An unauthenticated edge role user |
401 |
None |
| message/822, non-signed and encrypted body |
An authenticated but unauthorized (e.g., not the message sender) edge role user |
403 |
None |
| message/822 |
Message can not be parsed to verify required headers |
400 |
None |
| message/822, application/pkcs7-mime enveloped encrypted signed body |
Receiver can verify the message, or is a Source HISP and successfully delivers to a Destination HISP, or Destination prefers to receive signed and encrypted messages for local verification |
201 |
Location header providing the message-uri of the created resource |
Because the message-uri contains a message-id that is supplied by the message/822 content body, the following operation MUST be supported: A Source HISP MUST accept message/822 content that has a valid message-id supplied by the Source. Per the Content Container Specification the message-id message header is required.
Push to Destination
If a destination system supports the Messages POST interface, the HISP supports push to destination, and the networking landscape is appropriate, then a HISP MAY invoke the Messages resource on the destination system to deliver new messages to the destination. In this case the destination must implement the POST method on Messages resource as defined previously. The destination MUST follow all security requirements defined for HISP exposed interfaces as defined in this specification.
Note: The REST resource to invoke on the destination system would need to be available to the HISP in order to deliver messages. Configuration or maintenance of this information is considered an implementation detail of the HISP and is not addressed by this specification.
Message Resource
message-uri = messages-uri "/" message-id message-id = uuid "@" health-domain-name
The production rule for uuid is supplied by RFC 4122
The message-id in the URI MUST be the same message-id as found in the Internet Message Format Message Representation. (Note that, per RFC 5322, the content of the message-id does not contain the angle brackets found in the Message-ID RFC 5322 header.)
Message Retrieve Operation
An authenticated and authorized GET Request to the message-uri SHALL return a Message Resource representation if the server supports the representation accepted by the user agent.
The following protocol operations MUST be provided by implementations of this specification in response to a GET Request to the message-uri:
| Accept |
Conditions |
Response Status |
Response Content |
| message/822 |
User is authenticated and authorized, message exists |
200 |
The response body SHALL contain the message/822 representation of the requested message |
| Any |
User is not authenticated |
401 |
None |
| Any |
User is authenticated but not authorized |
404 |
None |
| Any |
Message ID does not exist |
404 |
None |
| Any |
Server does not support the content type requested by the User Agent with the Accept header |
406 |
None |
Message RFC 822 Representation
See Content Container Specification
Status Resource
The status resource is used by a destination to both retrieve the status of a message and to set the status of that message. Retrieving a message status is rarely done. The most common use is to mark a message as retrieved. Note that the status resource is not intended to take the place of end to end message delivery notification, but simply as a way for the destination system to mark a message as retrieved.
status-uri = message-uri "/status"
There are three status values that MUST be supported by an implementation of this specification
status-value = "NEW" | "ACK" | "NAK"
Status Retrieve Operation
An authenticated and authorized GET Request to the status-uri SHALL return a Status Resource representation.
The following protocol operations MUST be provided by implementations of this specification in response to a GET Request to the status-uri:
| Accept |
Conditions |
Response Status |
Response Content |
| text/plain |
User is authenticated and authorized, message exists |
200 |
The response body SHALL contain the status-value of the message. |
| Any |
User is not authenticated |
401 |
None |
| Any |
User is authenticated but not authorized |
404 |
None |
| Any |
Message ID does not exist |
404 |
None |
| Any |
Server does not support the content type requested by the User Agent with the Accept header |
406 |
None |
Status Update Operation
An authenticated and authorized PUT request to the status-uri SHALL update the message status.
The following protocol operations MUST be provided by implementations of this specification in response to a PUT Request to the status-uri:
| Content-Type |
Conditions |
Response Status |
Response Content |
| text/plain |
User is authenticated and authorized, message ID exists on HISP, and submitted status is a recognized value. |
200 |
None |
| text/plain |
Submitted status is not a recognized value. |
403 |
None |
| Any |
User is not authenticated |
401 |
None |
| Any |
User is authenticated but not authorized (i.e., not message receiver) |
404 |
None |
| Any |
Message ID does not exist |
404 |
None |
Source and Destination Authentication to HISP
HISP implementations MUST support the combination of HTTP Basic authentication combined with TLS, and MUST practice strong security measures to keep the authentication factors secure. Implementations MAY support additional authentication mechanisms defined by policy.
Security Considerations
Key considerations:
- All transactions MUST be over TLS encrypted channels
- Implementations MUST check TLS certificates for validity
- Implementations MUST verify certificates used for encryption and signature verification.
Examples
In this section we'll cover typical client workflow when sending and receiving messages.
Pull/Push Operation
In this example a client retrieves new messages via Pull operations and sends a message via Push operations.
Destination retrieves message from HISP
A client retrieves a list of messages from the HISP by making a GET request to the Messages resource:
GET /direct/v1/messages HTTP/1.1 Host: direct.uberhisp.com Accepts: application/atom+xml Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
The server responds with an atom feed of messages associated with addresses provisioned to the authenticated user:
example response goes here
The client then retrieves the first message by making a GET request to the Message resource:
GET /direct/v1/messages/UUID%40direct.otherhisp.com HTTP/1.1 Host: direct.uberhisp.com Accepts: message/rfc822 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
The server responds with an RFC 5322 encoded message:
--EXAMPLE RESPONSE GOES HERE--
The client then sends a PUT to the Message Status resource to indicate that the message was received and processed:
PUT /direct/v1/messages/UUID%40direct.otherhisp.com/status HTTP/1.1 Host: direct.uberhisp.com Content-type: text/plain Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ACK
The message has now been successfully retrieved and will not be returned with future GET calls to the Messages resource.
Source sends message to HISP
The client wants to send a new message. It constructs an RFC 5322 message compliant with the Content Container Specification and makes a POST call the the Messages resource:
POST /direct/v1/messages HTTP/1.1 Host: direct.uberhisp.com Content-type: message/rfc822 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== --EXAMPLE MESSAGE GOES HERE--
The server responds with an appropriate success message:
--EXAMPLE MESSAGE GOES HERE--
Push Only Operation
In this example the client system has negotiated (out of band) with the HISP for bi-directional push connectivity. POST to the Messages resource is invoked bi-directionally and is the only interface used.
Source sends message to HISP
The client wants to send a new message. It constructs an RFC 5322 message compliant with the Content Container Specification and makes a POST call the the Messages resource on the HISP:
POST /direct/v1/messages HTTP/1.1 Host: direct.uberhisp.com Content-type: message/rfc822 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== --EXAMPLE MESSAGE GOES HERE--
HISP sends message to Destination
The HISP receives a new message for a destination. It takes the RFC 5322 message and makes a POST call the the Messages resource on the Destination:
POST /direct/v1/messages HTTP/1.1 Host: access.bigemr.com Content-type: message/rfc822 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== --EXAMPLE MESSAGE GOES HERE--
Open Issues
Out of Band Addressing
The Content Security for Simple Health Transport Specification talks about routing messages based on addressing information in the SMTP conversation that could potentially be different from the addressing in the RFC 5322 message headers. This REST Edge Specification dictates that all routing be done based on the addressing in the RFC 5322 message. There is no provision for wrapping additional addressing. It's not clear what to do about this disconnect or whether it's meaningful. One option would be to add additional addressing to this REST Specification. Another option would be to tighten the SMTP Specification to clarify that non-SMTP down stream systems may be restricted to routing based on addressing in the message.
Authors
Arien Malec
Chris Moyer
Mark Stine
References
Bradner, Key words for use in RFCs to Indicate Requirement Levels, RFC 2119
Nottingham & Sayre, Atom Format, RFC 4287
Network Working Group, Internet X.509 Public Key Infrastructure: Operational Protocols: FTP and HTTP, RFC 2585
Leach et al., A Universally Unique IDentifier (UUID) URN Namespace, RFC 4122
Crocker, Augmented BNF for Syntax Specifications: ABNF, RFC 5234
Hansen & Vaudreuil, Message Disposition Notification, RFC 3798
Ramsdell & Turner, S/MIME 3.2 Message Specification, RFC 5751
Direct Project, Content Container Specification
Direct Project, Content Security for Simple Health Transport Specification
Copyright
By contributing to this specification, all contributors agree to license contributions according to the Creative Commons Attribution 3.0 License which is incorporated into this document by reference.