REST Edge Specification

From Direct Project
Jump to: navigation, search

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.

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:

  1. All transactions MUST be over TLS encrypted channels
  2. Implementations MUST check TLS certificates for validity
  3. 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.