NHIN DIRECT REST IMPLEMENTATION

Prepared by: The NHIN Direct REST Team

June 8, 2010

Some Definitions

» REST – Representational State Transfer» Introduced in Roy Fielding’s PhD thesis in 2000» Theory

• Requests and responses between clients and servers embody the transfer of “representations” of “resources”– Example: Resource is a “List of Messages”. Representations

could be an XML or HTML expression of the list.• Resource: Any addressable concept

» Practice• HTTP methods (typically GET, POST, PUT, DELETE) applied to

resources expressed as URIs• HTTP status codes for coarse-grained response interpretation• MIME Content-Type header for request and response interpretation

Why REST?

» Simple• Knowledge of HTTP method primitives, Content-Type, and URL

formation rules is all that is required» Ubiquitous

• HTTP is well understood with client libraries in virtually any environment and servers available for free

» Proven• HTTP has been the protocol of the web for years

» Extensible• New URL formation rules and Content-Type headers to address

new resources» Scalable

• REST HTTP-based services scale using well-understood techniques

Why REST?

» Integration Simplicity• Low level of knowledge needed (HTTP methods, headers, and URL

formation rules)» Tooling

• Lots of development tools to make coding simple (Spring MVC 3.0, JAX-RS, etc…)

» Natural X.509 certificate directory mechanism• /certs resource (more later)

Achievements

» REST Specification• http://nhindirect.org/REST+Implementation• Still some debate on the best way to architect the Abstract Model

status function (/status resource versus MDN)» Java-based HISP implementation (MedPlus/Quest & VisionShare)

• Spring MVC 3.0-based• REST backbone protocol. Demonstrated HISP to HISP messaging.• REST and SMTP/POP3 edge protocol support

– Functioning with standard email client & REST test clients– In prototype with MedPlus Care360 EHR as Source/Destination

• S/MIME message-based security (sign and encrypt). TLS between HISPs

• /certs resource for retrieving X.509 certificates

Achievements

» Ruby on Rails HISP implementation (Arien “private citizen” Malec)• REST backbone protocol• S/MIME message-based security (sign and encrypt)• /certs resource for retrieving X.509 certificates

» Java HISP implementation (Argonne National Labs)• REST backbone protocol• SAML integration

REST API Examples

» https://<HISP-domain>/nhin/v1/<health-domain-name>/<health-endpoint-name>/messages» Dr Johnson retrieving a list of messages from his HISP:

• https://hisp-a.com/nhin/v1/nhin.DodgeClinic.com/DrJohnson/messages• GET method• Returns an Atom feed containing URIs of available messages

» Dr Johnson retrieving a message from his HISP:• https://hisp-a.com/nhin/v1/nhin.DodgeClinic.com/DrJohnson/messages/8dc78b1e-4aea-

46a3-8317-43fe57ac5d6c• The UUID at the end of the URL is the message ID• Response format is an RFC 5322 email message

» HISP A posting a message sent by Dr. Johnson to Dr. Nelson• https://nhin.MetroCardiology.com/nhin/v1/nhin.MetroCardiology.com/DrNelson/messages• POST method• RFC 5322 email message format• nhin.MetroCardiology.com resolve in DNS to the IP of the HISP serving Dr. Nelson

» HTTP GET the X.509 certs (as an Atom feed) for DrJohnson@nhin.DodgeClinic.com• https://nhin.DodgeClinic.com/nhin/v1/nhin.DodgeClinic.com/DrJohnson/certs

Security & Trust

» S/MIME message-based signing and encryption is used by two of the three implementations for endpoint to endpoint privacy, authentication, integrity and non-repudiation.

• Ruby on Rails utilizes OpenSSL• Java (Spring MVC implementation) uses the nhin-d-jagent• HISP-to-HISP prototyping has been achieved

» Java (Spring MVC) still uses TLS for HISP to HISP on-the-wire privacy• Needed to protect To and From headers (potential PHI)• Still some debate about the desirability of client certificates

– They would stop nefarious traffic at the network level– They may imply a global HISP circle of trust

» Java (Argonne) uses SAML

Coding Experiences

» Java (Spring MVC)» Ruby on Rails» Java (Argonne)