REST Implementation Capabilities Worksheet
Jump to navigation
Jump to search
This worksheet outlines the capabilities of the proposed REST concrete implementation of the NHIN Direct specifications. The structure below follows the Implementation Capability Worksheet created by the Concrete Implementation Workgroup.
1. Overview
1.1. Provide a high-level end-to-end description of your implementation.
The REST implementation demonstrates quite clearly the power of building solutions on well-known, proven, simple, flexible, and scalable Internet technologies like HTTP. The simple NHIN Direct REST specification succinctly describes how NHIN Direct software components communicate with one another through HTTP method primitives (GET, PUT, POST), HTTP headers (e.g., Content-Type), and a simple set of rules for creating a well-formed URL. Because a REST-based specification can easily be extended through further URL specification, this approach is ideal for extending the NHIN Direct protocols into the future with as-yet-unforeseen use-cases. Powerful software development tooling exists (as shown by the Java Spring MVC-based REST proof-of-concept) that make REST development fast and easy.
The current NHIN Direct REST implementations include a Java Spring MVC-based HISP along with a Ruby-on-Rails-based HISP. Because the NHIN Direct REST protocol is network-based, the Ruby-on-Rails and Java HISPs easily communicate using the common HTTP-based backbone protocol. A python-based and a Ruby-based Source or Destination actor is used to communicate to either HISP via REST. In addition, a TLS-based SMTP/POP3/IMAP edge protocol was integrated into the Java HISP and an off-the-shelf e-mail client (Windows Live Mail) was used as a Source and Destination actor. The wide variety of implementation languages and off-the-shelf software demonstrates the feasibility of using a simple REST-based approach to integrate a wide variety of environments together.
1.2. Provide a diagram representing the software blocks required for a representative end-to-end system implementation
1.3 Describe the current overall state of the implementation
A Java Spring MVC-based HISP has been coded along with a Ruby-on-Rails HISP. Both implement the full NHIN Direct REST specification. Python-based and Ruby-based Source actors were created to test the HISP interfaces. HISP-to-HISP communication over mutually authenticated TLS has been demonstrated. An SMTP/POP3/IMAP edge protocol was added to the Java HISP via Apache James, and an off-the-shelf e-mail client (Windows Live Mail) was successfully used as a Source/Destination actor.
An S/MIME-based implementation of the security and trust workgroup consensus document has been completed in both the Ruby on Rails and Java HISP code (see section 6 below).
1.4 Describe the working group participants and contributions
| Name |
Affiliation |
| Arien Malec |
Private (not representing NHIN Direct in this effort) |
| David Kibbe |
Clinical Groupware Collaborative |
| Paul Saxman |
Google |
| Chris Moyer |
MedPlus/Quest Diagnostics |
| Mark Stine |
MedPlus/Quest Diagnostics |
| Bill Becker |
VisionShare |
| Brett Peterson |
VisionShare |
2. Benefits/Drawbacks
2.1 Outline why you believe this is the best approach to achieving the goals of NHIN Direct.
Using a REST approach to NHIN Direct protocols provides the following benefits:
- Proven Technology: HTTP has been proven as a reliable underlying fabric of the Internet.
- Well Known: HTTP is a protocol familiar and well-known to millions of software developers.
- Simplicity: Knowledge of HTTP method primitives (GET, PUT, POST) with a few well-known headers (Content-Type) and simple rules for URL formation is all a programmer needs to know.
- Minimal Complexity for Most Use Cases: While integration with SOAP and WS-* based IHE and NHIN Exchange protocols is possible through a gating mechanism, the vast majority of clinical messaging can run across the simple HTTP-based REST protocol thus minimizing complexity for most developers and speeding time to market.
- Development Tool Support: Production quality development tools for REST APIs exist in virtually every environment (e.g., Spring MVC 3.0 REST-centric annotations).
- Web Server Support: HTTP servers are mature and provide natural enhancements like caching, proxies, etc...
- Extensibility: When additional interoperability capabilities need to be added to the NHIN specifications, a REST approach will allow this evolution through easy new URL formation rules and Content-Type headers. The URL syntax itself already contains a version element (i.e., v1) thus allowing an easy path to future capabilities.
- Natural X.509 Certificate distribution: With message-based encryption and signing in place (e.g., S/MIME) the REST approach provides a naturally distributed distribution mechanism for certificates by defining a URL for that purpose (thus avoiding the need for DNS CERT resource records).
- EMR Integration Simplicity: Integrating with existing EMR systems is simplified by the low level of knowledge necessary to code to the API (HTTP methods, headers, and URL formation) and by the large numbers of HTTP client toolkits.
- Extensive Use in Existing Healthcare Exchange: Surescripts APIs, Google Health's APIs, RelayHealth APIs, VisionShare APIs, and others.
2.2 Outline any Drawbacks to this approach
The REST approach will require that code be written which can be both a benefit and a drawback. New code implies testing and hardening; however, if the REST API is kept relatively small that effort could be minimized. New code along with a well-designed URI format can assist with future extensibility as well.
Although this applies to all choices (except a pure XD*-based solution), this approach needs to define a technological bridge into the current NHIN Exchange from both a protocol and content packaging perspective.
3. Specific Artifacts
3.1 Describe the status of working code.
A Java Spring MVC-based HISP has been coded along with a Ruby-on-Rails HISP. Both implement the full NHIN Direct REST specification. Python-based and Ruby-based Source actors were created to test the HISP interfaces. HISP-to-HISP communication over mutually authenticated TLS has been demonstrated. An SMTP/POP3/IMAP edge protocol was added to the Java HISP via Apache James, and an off-the-shelf e-mail client (Windows Live Mail) was successfully used as a Source/Destination actor.
An S/MIME-based implementation of the security and trust workgroup consensus document has been completed in both the Ruby on Rails and Java HISP code (see section 6 below).
Real-world EHR applications are being explored as possible alpha Source actors.
3.2 Describe the status of written specifications.
The REST Implementation page describes the NHIN Direct REST protocol in detail and maps it to the NHIN Direct Abstract Model actors and transactions.
3.3 Describe the status of test tools and cases.
Unit tests exist for both the Java and Ruby HISP code. In addition, Python, Ruby, and SMTP test clients regularly exercise the HISP functionality.
3.4 Describe the production readiness of the working code e.g., are errors and edge cases handled, are administrative and monitoring tools available, etc.
The code is currently in a proof-of-concept state.
4. Abstract Model
4.1 Describe how each numbered transaction is supported by the implementation.
The mapping to the Abstract Model's transactions is included at the bottom of the REST specification.
4.2 Describe how each defined "term" in the abstract model is instantiated in the implementation.
The mapping to the Abstract Model's terms is included near the top of the REST specification.
5. User Stories
5.1 Describe how each user story is supported by the implementation. ALL stories regardless of priority should be addressed; working code may be focused on the priority 1 items.
All NHIN Direct user stories involve the push of a message from a Source to a Destination through one or two logical HISPs. The REST implementation follows the Content Container Specification and routes messages based on "From" and "To" headers. In that sense, all NHIN Direct user stories are supported by this implementation as long as the Source or Destination speak a supported Edge Protocol. In some cases (e.g., a large PHR) a system may play both Source and Source HISP roles or Destination and Destination HISP roles simultaneously. Such deployment scenarios are likely to be utilized when supporting the Patient side of Provider-to-Patient use-cases.
6. Security & Trust
6.1 Describe how each consensus requirement is supported by the implementation.
The Security & Trust workgroup appears to be nearing consensus on the S&T Consensus Proposal v3 document. The REST implementation uses an S/MIME approach to fulfill the requirements agreed to by the Security and Trust Workgroup. Specifically, message integrity and non-repudiation are achieved through a message-based S/MIME signature using the private key of the Source (often times executed by the Source HISP). Verification of the signature at the Destination HISP (or possibly the Destination) requires the X.509 public certificate corresponding to the private key used to generate the signature. Message privacy is achieved through asymmetric encryption using the public X.509 certificate (public key) of the Destination. Decryption of the message is only possible using the private key of the Destination thus guaranteeing privacy in transit and at rest.
S/MIME expresses the X.509-based privacy and integrity features described above in standard multipart MIME types and headers. This fits well with the MIME-based Content Container Specification.
All X.509 public certificates are obtained through the Certificates REST resource. Certificates may be issued at the organization or individual level.
The HISP-to-HISP transactions use TLS primarily to mitigate against on-the-wire snooping of metadata (such as To and From addresses) that could be considered Protected Health Information (PHI).
7. Comprehensive HIE
7.1 Describe the mechanisms by which the implementation can interact with NHIN Exchange implementations.
It is likely that the vast majority of push-based communications occurring through NHIN Direct (particularly provider to provider or provider to patient) will not need to involve an endpoint implemented using NHIN Exchange protocols (e.g., SOAP, WS-*, SAML, etc...). The extra complexity and processing time of translating to and from NHIN Exchange formats and protocols is only needed if one of the endpoints currently speaks NHIN Exchange protocols. As such, integration with the NHIN Exchange could occur through a message and protocol translation layer located at the HISP. In essence, the NHIN Exchange Node plays the role of Source or Destination. This approach keeps the NHIN Direct communications lean and simple and only requires translation to NHIN Exchange protocols when necessary.
For example, the NHIN CONNECT implementation of the NHIN Exchange protocols would require an NHIN CONNECT adapter for "stepping up" or "stepping" down to/from NHIN Direct. The NHIN CONNECT node would be either a Source or Destination actor.
8. Other Workgroups
8.1 If the implementation deviates from requirements of the Addressing, Content Packaging or Individual Involvement workgroups, describe and explain the reasons here.
The REST implementation does not deviate from any of the listed requirements.
9. Cost and complexity of development
9.1 Describe what new code is required to create a complete implementation vs. what can be used off-the-shelf.
New code needs to be written to implement the semantics of the REST API for all actors. Standard HTTP server products can be used to host the products.
9.2 Describe library and required component availability across platforms and frameworks.
Proven HTTP servers exist in abundance. Programmatic support for easily implementing HTTP-based REST clients exist in many popular platforms (e.g., Java has JAX-RS and Spring MVC). Even in the absence of tooling support for REST, the HTTP protocol itself is simple and transparent and can be coded to directly.
9.3 How does this approach integrate with existing mainstream healthcare applications? Describe cost/complexity of integration.
Existing EHR systems written in virtually any environment have the capability to easily program to HTTP. The complexity is low and HTTP client libraries exist in almost every language/environment.
10. Workflow / User Experience
10.1 Describe how a small (1-5 provider) practice with limited IT capability might deploy and service the implementation.
"Limited IT capability" here is construed to mean that a physician/practice has Internet connectivity and either technology no more sophisticated than an email client or Web browser, or an "EHR module" such as a disease registry or ePrescribing application, but not a "complete EHR."
The first step for the physician would be assignment of a domain name. This could be done by purchasing a domain name or creating an account at an entity with a domain. For purposes of illustration, we'll use "PrimaryCareCenter.org" as the domain name for DrSmith, whose email address is DrSmith@PrimaryCareCenter.org. We expect that HISPs will provide a domain name to client physicians and practices for a small fee.
The second step is for the practice to assign a subdomain for the purpose of NHIN-D exchanges. Again, HISPs will do this, as may some ISPs. For Dr. Smith, this would become drsmith@nhin.PrimaryCareCenter.org. The associated REST URI for DrSmith would be https://nhin.PrimaryCareCenter.org/nhin/v1/nhin.PrimaryCareCenter.org/drsmith/
The third (possibly optional) step would be for the practice to enter its assigned domain in the email client software, and then set up a username + API key (SMTP/IMAP based client adaptor) provided by its HISP. The HISP is also able to provide the certificate for the physicians in the practice.
If the practice/physicians will use a Web-based client supplied by the HISP as their NHIN-D email client, then the third step above would not be necessary.
Finally, if the practice wishes to use its EHR module to send and receive NHIN-D message content, then it would configure the software to use its URL to interact with the HISP's RESTful API. The EHR module vendor would assist the practice to achieve this.
10.2 Describe how a medium practice with an outpatient EMR might deploy and service the implementation.
The outpatient EMR would likely implement the Source and Destination actors and REST API transactions with HISPs. An outpatient EMR could implement the HISP role, but in most cases would contract with a dedicated HISP entity. Either way, the integration could be accomplished with a relatively small amount of code from any environment supporting HTTP and TLS.
10.3 Describe how a large practice / hospital might deploy and service the implementation.
Most large practices and hospitals contain EMR systems that control the clinical workflow at and between institutions. To integrate with the REST API, the EMR system would need to implement certain REST transactions as defined in the NHIN Direct REST Specification depending on what type of actor it intends to be. A large practice could be a HISP on its own or could only implement the Source and Destination-related transactions. Most importantly, this integration could be accomplished from any environment supporting HTTP and TLS.
10.4 Describe how a patient might participate in the implementation.
A patient would participate using a PHR service that would implement the entire NHIN Direct REST API (all actors) or implement only the Source and Destination actors thus relying on a third-party HISP organization. The interface presented to the patient would be fully dependent on the PHR service.
10.5 Describe how a service provider might create and operate an implementation.
The answer to this questions depends on what is meant by a Service Provider. An entity could implement the HISP role and present the server side of the Source-to-HISP and Destination-to-HISP transactions.
11. Miscellaneous
11.1 Metadata Handling
11.1.1 Describe what metadata inherently handled by the implementation
Any metadata beyond that currently included for message routing (To, From, etc...) should not be addressed at the protocol level. Rather this is an issue that should be handled by the Content Container Specification thus making it opaque to the REST specification itself. As documented in the Content Container Specification, the minimal metadata includes content type, and optional manifest data through the use of XDM attachments, but may further be signed and encrypted, and nothing in the REST specification requires access to the content body.
11.1.2 Explain how more complex metadata could be added to the implementation if it is desired
More complex metadata should be addressed only by the Content Container Specification and should not be designed into the REST communication protocol. As documented in the Container Container Specification, complex metadata is addressable through the use of XDM attachments.
11.2 Content Handling
11.2.1 Describe how the implementation deals with unstructured text content.
The REST implementation follows the Content Container Specification, thus unstructured text content is packaged as one part of a multipart MIME package with an appropriate Content-Type header.
11.2.2 Describe how the implementation deals with unstructured binary content (e.g., PDF).
The REST implementation follows the Content Container Specification, thus unstructured binary content is packaged as one part of a multipart MIME package with an appropriate Content-Type header (typically base64 encoded).
11.2.3 Describe how the implementation deals with structured content such as CCx.
The REST implementation follows the Content Container Specification, thus structured content is packaged as one part of a multipart MIME package with an appropriate Content-Type header.
11.3 Extensibility / Future-proofing
11.3.1 How would this implementation approach extensibility in general to support new use cases?
To support new use-cases, the REST specification simply needs to be extended with additional semantics tied to new URL rules. Extensibility and future-proofing are two of the strong benefits of a REST approach.