Coming to REST, Part II: It’s All About Resources

Ultimately, REST is about accessing resources.  Efficient and effective use of resources requires that all components make use of a uniform interface for all interactions.   Roy Fielding lists four constraints that interfaces must follow in order to meet REST specifications.

Identification of Resources All resources must have a unique ID (e.g., URL)
Access of Resources via Representations Representations (e.g., HTML Document, JPEG, PDF)
Self-descriptive Messages Everything needed to fulfill a request must be sent with the requesting message
Hypermedia-based Application State Hyperlinks provide access to resources. The client changes application state by accessing links.

Table 2 – Uniform interface constraints

If this all seems a bit abstract, that’s because it is. After all, we are talking about software architecture.  However, we are past most of the abstract stuff and just about ready to look at the practical implications of REST.

A Bit More about Resources and Representations
As can be seen from Table 2, a resource is not a single thing like a PDF file.   Rather, Fielding defines a resource as a “conceptual mapping to set of entities.”   Further, the set that a resource maps to may contain either representations (PDFs, HTML documents, Excel Files, etc.)  or resource identifiers (i.e., URLs).     Thus, since a resource maps to a set, the contents of a resource may be NULL (there is nothing there),  contain additional resource identifiers (URLs/links), or the actual file you are looking for (a representation).  Got that?

Fielding offers the following explanation for his way of defining resources:

This abstract definition of a resource enables key features of the Web architecture. First, it    provides generality by encompassing many sources of information without artificially distinguishing them by type or implementation. Second, it allows late binding of the reference to a representation, enabling content negotiation to take place based on characteristics of the request. Finally, it allows an author to reference the concept rather than some singular representation of that concept, thus removing the need to change all existing links whenever the representation changes (assuming the author used the right identifier).

If this is still confusing, think about resource/representation mapping as a mechanism for allowing a resource to have multiple representations.   For example, patient John Doe’s demographic information could be made available as a data set returned from a query, PDF, JSON file, or XML file. These are all representations of the same resource—his demographic information; however, each would have a different URL.

Let’s finish the abstract discussion with a look at the definition of representation.   A representation is defined as a “…sequence of bytes plus metadata to describe those bytes.”    This generic definition covers anything that could be rendered in digital form.

REST in Action
Now that you have been introduced to the main concepts (there is more to REST), it is time to see why so many are embracing REST for web services/APIs.   Remember, REST focuses on resources, representations, and links.

Accessing RESTful Resources
Since REST is designed for use on the web, it makes use of HTTP.   The HTTP protocol offers four methods (also referred to as verbs) that may be used to manipulate resources: GET, POST, PUT, and DELETE.   GET and POST are commonly used in HTML web forms.  If you’ve done a search or submitted a web form, you have used these methods.  RESTful APIs standardize their usage and map them to the following actions.   (Here, I am assuming the resource is mapped to a data store, but that’s not required.)
GET – Retrieve a resource ( retrieve a patient from a database)
POST – Create a resource (add a patient to a database)
PUT – Update a resource  (update the patient’s information)
DELETE – Delete (you get the idea…)

System designers who wish to share data with others create links to their resources that outside users can follow to gain access. It is really that simple.

Drug Information Example
Let’s look at an example in which a company, Drug Info Store, Inc., provides EHR designers with drug information via a RESTful API.  Here are a few URLs that might be offered to clients.

Retrieving a list of all drugs, which is a collection/set, from the database:

Assuming that furosemide has drug ID 1234, a drug monograph for it could be obtained using the URL below:

The actual HTTP Request would look something like this:
GET /drugbase/drugs/1234     HTTP/1.1

Assuming that a drug interaction query already exists in the database, a request for all drugs known to interact with furosemide could be submitted as:

Consider how easy it is to obtain information from the drug database!  When system designers make their APIs public, it becomes much easier to determine what they are making available and how it is best accessed.  These REST API examples from Facebook  and Twitter are but two examples of how public APIs make data sharing more straightforward and less time-consuming to implement.

Of course, REST is also a great way for enterprises to provide interactions between their system components.  The beauty of using modular, loosely-coupled systems is that they can be designed, built and deployed independently and still work well together. For example, suppose a hospital group decides to create a disease registry to track patients with diabetes.   If the registry offers a RESTful API, new patients can be added directly from an EHR by converting the patient’s data to JSON format and submitting it with the POST method.

EHR with APIs

REST is really catching on.  It is designed for the web, and everything needed to take advantage of the architecture is already in place.  It is simpler to use, more uniform and lighter-weight than SOAP and RPCs,  and based on my admittedly limited experience, easier to understand.   Ultimately, however, the  value of an architectural style such as REST lies in the flexibility it provides in creating scalable systems that are easy to extend and able to change with the times—capabilities that are essential in modern EHRs.


Leave a Reply

Your email address will not be published. Required fields are marked *