REST 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 NHIN Direct project IPR Policy.
Abstract
This specification provides a mapping of the NHIN Direct Abstract Model to Representational State Transfer (REST) HTTP resources.
Table of Contents
Introduction
Purpose
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 services described in this document.
This specification provides a uniform set of resources provided by each HISP:
| Resource |
Resource Description |
| Messages |
The set of messages sent to an address |
| Message |
An individual message sent to an address |
| Message Status |
The status of a message resource |
| Certificates |
X509 certificates corresponding to an endpoint |
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 whose To: header contains the Health Internet Address represented in the <endpoint-path>. If the Destination HISP is identical to the Source HISP, creates the message and returns a resource whose Location header is the URI to the newly created message. If the To: header represents a remote address (served by a different HISP), will mirror this POST to the Destination HISP, and mirror the response to the Source |
| Message |
GET |
Accept: message/rfc822 |
A health content container representing the message at the specified resource |
| Message Status |
GET |
Accept: TBD |
Returns a representation of the indicated message status |
| Message Status |
PUT |
Content-Type: TBD |
Updates the selected message status. If the PUT is at the Destination HISP, mirrors the PUT operation to the Source HISP and mirrors the response to the Destination |
Health data security and trust are provided by using S/MIME to sign and encrypt RFP 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.
Terminology
The terminology adopted in the NHIN Direct Abstract Model, Content Container Specification and Addressing Specification is also adopted in this document.
URIs, Resources, and Protocol Operations
Base URI
health-domain-name = Health Domain Name
The definition of health-domain-name is provided in the addressing specification. Owners of the Health Domain Name MUST ensure the Health Domain Name is resolvable via the DNS to an HTTPS service running on the well-known HTTPS port.
base-uri = "https://" health-domain-name "/nhin" 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://exchange.nelsoncardiology.example.org/nhin/v1 https://nhin.bigidnco.example.com/nhin/v1
Endpoint Base URI
endpoint-base-uri = base-uri "/" address-path address-path = health-domain-name "/" health-endpoint-name
The definitions of health-domain-name and health-endpoint-name are provided in the addressing specification
The Endpoint Base URI provides resources corresponding to a valid Health Internet Address. This specification does not define implementation behavior to HTTP methods applied to the Endpoint Base URI.
Non-normative examples of an Endpoint Base URI include:
https://exchange.nelsoncardiology.example.org/nhin/v1/exchange.nelsoncardiology.example.org/jones https://exchange.nelsoncardiology.example.org/nhin/v1/nhin.bigidnco.example.com/smith
Note in the second example that an Endpoint Base URI MAY be provided at a Health Domain Name that is different from the Health Domain Name for the endpoint. Examples of how why this may be done are provided in the Messages Resource section of this document.
Certificates Resource
certificates-uri = endpoint-base-uri "/certs"
The Certificates Resource provides representations of the public X.509 certificates corresponding to the Health Internet Address. Such certificates MAY be used to encrypt messages sent to the endpoint, verify signatures associated with the endpoint, or verify the details of the certificate.
Implementations MUST provide an Atom representation of the Certificates Resource in response to a GET request at that resource, when the GET request contains an Accept: header of application/atom+xml.
The Atom representation MUST be a valid Atom document, corresponding to RFC 4287. The Atom document MUST include one entry element per public certificate, and each entry MUST contain a content element of type application/pkix-cert, containing the DER-encoded certificate representation, Base64 encoded per the Atom specification.
Implementations MUST NOT authenticate, authorize, or otherwise filter GET requests to the Certificates Resource (as these are the public keys of the provider, there is value in making them generally and widely available).
A non-normative example of an Endpoint Base URI is:
https://exchange.nelsoncardiology.example.org/nhin/v1/exchange.nelsoncardiology.example.org/jones/certs
A non-normative example of a Certificates Resource Atom Representation is:
<?xml version="1.0" encoding="UTF-8"?> <feed xml:lang="en-US" xmlns="http://www.w3.org/2005/Atom"> <id>tag:drjones@nhin.happyvalleypractice.example.org,2005:certs</id> <link type="application/atom+xml" href="https://nhin.happyvalleypractice.example.org/nhin/v1/nhin.happyvalleypractice.example.org/drjones/certs" rel="self"/> <title>Certificates for drjones@nhin.happyvalleypractice.example.org</title> <updated>2010-06-09T17:59:35Z</updated> <entry> <id>tag:drjones@nhin.happyvalleypractice.example.org,2005:certs/438678246</id> <published>2010-05-26T18:34:38Z</published> <updated>2010-05-26T18:34:38Z</updated> <title>Certificate for drjones@nhin.happyvalleypractice.example.org</title> <summary>Certificate for drjones@nhin.happyvalleypractice.example.org</summary> <author> <name>drjones@nhin.happyvalleypractice.example.org</name> <email>drjones@nhin.happyvalleypractice.example.org</email> </author> <content type="application/pkix-cert">MIIChDCCAe0CAQEwDQYJKoZIhvcNAQEFBQAwgYMxCzAJBgNVBAYTAlVTMQsw CQYDVQQIEwJDQTEQMA4GA1UEBxMHT2FrbGFuZDEUMBIGA1UEChMLTkhJTiBE aXJlY3QxFDASBgNVBAMTC05ISU4gRGlyZWN0MSkwJwYJKoZIhvcNAQkBFhph cmllbi5tYWxlY0BuaGluZGlyZWN0Lm9yZzAeFw0xMDA1MjAxNzM0MjdaFw0y MDA1MTcxNzM0MjdaMIGQMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExEDAO BgNVBAcTB09BS0xBTkQxFjAUBgNVBAoTDUxpdHRsZSBISUUgQ28xHzAdBgNV BAMTFkxpdHRsZSBISUUgQ28gb3BlcmF0b3IxKTAnBgkqhkiG9w0BCQEWGmFy aWVuLm1hbGVjQG5oaW5kaXJlY3Qub3JnMIGfMA0GCSqGSIb3DQEBAQUAA4GN ADCBiQKBgQClEcq+PnXMMfTKjEXqn1n7OxyhTxxsjTHPXJ/Mp/uu2tHcrF5z HHs/uRChEP5XODwYyfXjJM5+5IVgJmKEhmaisxSPA/bOc4UVcLcyvsPr43f3 0Ua0WKDn30js4UUr+JqBS70yyfqOxWSmZJJo43u42q0+AfQQt4dw8tJyzmgE 9wIDAQABMA0GCSqGSIb3DQEBBQUAA4GBACEEhfU0ibFM73emNPpP5sBZ0CSk X535UhBPViVUV5XVQYJ57d3L0yZQRQrSCOSOWQ9bN2eszVslh1D33YmonW1n py8W84AshDGYYp4KjHEeQr+pQfoUm46+e1tOC22KNeJi7YhDs2yqD7b4mDr6 WDtMSuewfapVEJdzsTDTRdWz </content> </entry> </feed>
Messages Resource
messages-uri = endpoint-base-uri "/messages"
The Messages Resource represents messages sent to the specified Health Internet Address.
Note that the endpoint-base-uri MAY include different health-domain-name values for the HTTPS server domain and the Health Internet Address domain.
A non-normative example of a URI serving this need would be:
https://exchange.nelsoncardiology.example.org/nhin/v1/nhin.bigidnco.example.com/smith/messages
This URI would allow operations by jones, an addressable endpoint at exchange.nelsoncardiology.example.org with respect to smith, an addressable endpoint at nhin.bigidnco.example.com, including creating a message resource that is sent by the Source HISP to nhin.bigidnco.example.com.
Messages List Operation
An authenticated and authorized GET Request to the messages-uri SHALL provide a list of messages sent to the Health Internet Address.
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.
Implementations MAY support access to Messages Lists representing status values other than NEW through query parameters or subresources and MAY support other representations.
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 (possibly at a remote HISP).
The semantics are to create a message to the address represented by the address-path. If a Source wishes to send a message to multiple destinations, the Source MUST create a message resource for each receiver.
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 |
| message/822, application/pkcs7-mime enveloped encrypted signed body |
Destination HISP can not decrypt message or, once decrypted, can not verify the message signature |
403 |
None |
The following protocol operation MAY be provided by implementations that provide asynchronous delivery. Clients MUST be prepared to receive a 202 status.
| Content-Type |
Conditions |
Response Status |
|
| message/822 |
The HISP has accepted the message and may deliver asynchronously |
202 |
Location header providing the message-uri of the resource to be created; the status resource MUST be immediately available to allow the Source to check delivery and receipt status |
Because the message-uri contains a message-id that is supplied by the message/822 content body, the following operations MUST be supported:
- A Source HISP MUST accept message/822 content that has a valid message-id supplied by the Source
- If the Source HISP receives message/822 content that does not have a message-id, the Source HISP MUST create a valid message-id and associated message/822 header
- A Destination HISP receives a message/822 that has been signed and encrypted, and MUST verify the presence of a valid message-id and MUST NOT create a message-id if not present. Instead, it MUST respond with an error status.
In cases where the Source and Source HISP are separate entities, and the Source HISP has been delegated by the Source to perform signing and encryption, the Source will POST the message representation to the Source HISP with an address-path of the address to which the message is being sent. The Source HISP will then sign and encrypt and either synchronously POST the message representation to the same path portion of the messages-uri to the Destination HISP by using the health-domain-name of the addressed Health Internet Address in the domain portion of the messages-uri, and echo the HTTP status and required response content back to the Source; or will queue the message for asynchronous delivery.
The overall flow for successful synchronous delivery is:
Source Source Destination | HISP HISP |----POST----> | | | | | | |--- | | | | | | | Sign | | | and | | | encrypt | | | | | | |--- | | | | | |------POST------>| | | |--- | | | | | | | Decrypt | | | and | | | verify | | | | | | |--- | |<---Response-----| | | 201 + Location | |<--Response---| | |201 + Location| |
The overall flow for successful asynchronous delivery is:
Source Source Destination | HISP HISP |----POST----> | | | | | | |--- | | | | | | | Sign | | | and | | | encrypt | | | | | | |--- | |<--Response---| | |202 + Location| | | | | | |------POST------>| | | |--- | | | | | | | Decrypt | | | and | | | verify | | | | | | |--- | |<---Response-----| | | 201 + Location | | | | |-----GET----> | | | Status | | | | | |<--Response---| | |200 + Status | |
Assuming the Health Endpoint Name jones at Health Domain Name exchange.nelsoncardiology.example.com is initiating this transaction, the first POST in the sequence (from Source to Source HISP) would be to:
https://exchange.nelsoncardiology.example.org/nhin/v1/nhin.bigidnco.example.com/smith/messages
And the second POST (from Source HISP to Destination HISP) would be to:
https://nhin.bigidnco.example.com/nhin/v1/nhin.bigidnco.example.com/smith/messages
Other variations are possible:
- If both addresses are served by the same HISP, the Source will POST to the Source HISP, which will create the message locally and format the response accordingly.
- If the Source can sign and encrypt, it may follow the above flow (in which case the Source HISP will replay to the Destination HISP without further processing) or may POST directly to the Destination HISP
The value of the location header returned by the Source HISP in the full flow will be to a URI whose host is the Source's Health Domain Name, rather than the Destination's Health Domain Name. This allows the Source to query the Status Resource at a host for which the Source has authenticated credentials.
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
status-uri = message-uri "/status"
Status Retrieve Operation
An authenticated and authorized GET Request to the status-uri SHALL return a Status 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 status-uri:
| Accept |
Conditions |
Response Status |
Response Content |
| message/rfc822 |
User is authenticated and authorized, message exists |
200 |
The response body SHALL contain the MDN representation of the requested status |
| 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 if the server supports the representation supplied by the user agent.
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 |
| message/rfc822, unsigned and unencrypted message/report body |
User is authenticated and authorized, message Source is local to the HISP or message Source is remote and status is updated remotely through a successful synchronous operation |
200 |
None |
| signed and encrypted body |
Status is decrypted and verified successfully by Source HISP or Source prefers to decrypt and verify locally |
200 |
None |
| signed and encrypted body |
Status can not be decrypted or signature can not be verified |
403 |
None |
| unsigned and unencrypted body |
User is not authenticated |
401 |
None |
| unsigned and unencrypted body |
User is authenticated but not authorized (i.e., not message receiver) |
404 |
None |
| Any |
Message ID does not exist |
404 |
None |
The following protocol operation MAY be provided by implementations that provide asynchronous delivery. Clients MUST be prepared to receive a 202 status.
| Content-Type |
Conditions |
Response Status |
Response Content |
| The Destination HISP has accepted the status, the Source HISP is not the Destination HISP, and the Destination HISP will deliver asynchronously |
202 |
Location provides a single purpose URI that may be used to find the HTTP status of the asynchronous transaction. That URI MUST be unique to the Status Update Operation, MUST NOT follow a production rule otherwise specified in this document, but otherwise MAY be any valid URI. In response to a GET or HEAD request to that URI, the URI MUST return either status 202, to indicate that the status update has not been delivered, or the status returned by the Source HISP. The response MUST be used solely for the purposes of discovering the status of the original PUT request, and MUST NOT return any body content or headers that contain Protected Health Information. |
The overall flow for successful synchronous delivery is:
Source Source Destination | HISP HISP |-----PUT----> | | | | | | |--- | | | | | | | Sign | | | and | | | encrypt | | | | | | |--- | | | | | |-------PUT------>| | | |--- | | | | | | | Decrypt | | | and | | | verify | | | | | | |--- | |<---Response-----| | | 200 | |<--Response---| | | 200 | |
The overall flow for successful asynchronous delivery is:
Source Source Destination | HISP HISP |-----PUT----> | | | | | | |--- | | | | | | | Sign | | | and | | | encrypt | | | | | | |--- | |<--Response---| | |202 + Location| | | | | |-----HEAD---->| | | to Location | | |<--Response---| | | 202 | | | |-------PUT------>| | | |--- | | | | | | | Decrypt | | | and | | | verify | | | | | | |--- | |<---Response-----| | | 200 | |-----HEAD---->| | | to Location | | |<--Response---| | | 200 | | | | |
Status Resource MDN Representation
The Status Resource MDN Representation SHALL be an RFC 3798 Message Disposition Formatted Internet Message Format document.
The following clarifications and changes are applied in the use of RFC 3798 by this document:
disposition-type = "displayed"
/ "dispatched"
/ "processed"
Note that the production grammar for RFC 3798 removes the processed and dispatched values from the disposition-type definition, but refers to them in the RFC text.
The disposition-type of dispatched SHALL be interpreted to mean that the message has been accepted by the Source HISP but has not been delivered to the Destination HISP.
The disposition-type of processed SHALL be interpreted to mean that the message has been accepted by the Destination HISP but has not been delivered to the Destination.
The disposition-type of displayed SHALL be interpreted to mean that the message has been delivered successfully to the Destination.
The disposition-type of deleted, defined in RFC 3798, is not defined in this specification.
When the disposition-modifier is error, the error-field MUST be provided, and SHOULD provide error text that is formatted according to the error handling rules for the content that was transmitted (for example, HL7 V2 error reporting for HL7 V2 messages).
Source and Destination Authentication to HISP
HISP implementations MUST support the combination of HTTP Basic authentication combined with mutual TLS with a client certificate, and MUST practice strong security measures to keep the authentication factors secure. Implementations MAY support additional authentication mechanisms defined by policy.
Internet Message Format Encryption and Signature Operations
HIGH LEVEL FLOW: TODO: BETTER DETAIL
Follows RFC 5751. Also MUST include the subject header in the content package to be signed and encrypted.
Send
- The receiver's certs resource is queried to discover the current certificates in use
- The receiver's certificates are examined to determine validity and common anchors with the sender's supported certificates
- A receiver certificate + sender certificate and key pair are selected that have a common anchor.
- If no common anchor is discovered, error
- The content package (the body with the content-* headers and the subject header) is extracted
- The content package is signed with the receiver certificate
- The content package is encrypted with the sender's private key and certificate
Receive
- The sender's certs resource is queried to discover the current certificates
- The sender's certificates are examined to determine validity as of the date-time of the message transmission
- All sender certificate + receiver certificate and key pair are selected that have a common anchor
- If no common anchors are discovered, error
- For each sender certificate, attempt to decrypt the message and test if the message has a valid signature
- If so, test the signature's validity with each of the matching receiver certificates + key pair
- If the message is successfully decrypted and signature verified, success
- If all sender certificates are exhausted, error
Note that the sender algorithm MAY be applied either at the Source or the Source HISP, and the receiver algorithm MAY be applied at either the Destination HISP or the Destination. The sender algorithm MUST be applied prior to transfer to the Destination HISP.
Security Considerations
TO BE COMPLETED AFTER RISK ANALYSIS.
Key considerations:
- All transactions (Source/Destination to HISP and HISP-HISP) MUST be over TLS encrypted channels
- Implementations MUST check TLS certificates for validity
- Implementations MUST verify certificates used for encryption and signature verification.
Examples
This section is non-normative.
Authors
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
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.