RESTful+Design+and+Organization+of+Content

include component="page" wikiName="siframework" page="RHEx Header" flat = RESTful Service Actions Mapping = RESTful services focus on resources. A resource can be thought of as a noun. A patient, medication or order list could be a resource. RESTful services then allow interactions with these resources through the CRUD actions, which stand for Create, Read, Update and Delete. =READ= Actions such as read have a very simple mapping to an HTTP method, in this case, GET. However, for other CRUD actions, the mapping is not so simple, which leads to variations in service implementations. =CREATE= Create has at least two different ways of being implemented in a RESTful architecture. One way to create a resource in a RESTful system is by interacting with a resource collection. For instance, if you wanted to create a new lab result resource, you would interact with a lab result list resource. To do this, you would use the HTTP POST method on the lab result collection. The body of the HTTP request would contain all of the information necessary for creating a lab result resource. The server then stores the information, generates a unique identifier for the new lab result resource and notifies the client where it will be hosted. This is the approach taken by [|OData], [|hData] and [|AtomPub].

Alternatively, the responsibility of generating a unique identifier can be shifted to the client in a RESTful architecture. Some solutions will prefer that clients use the HTTP PUT method to create a resource. In this case, the client will determine the location where the resource will be hosted. This the current approach used by [|IHE MHD].

This instance of variation in service design is one of several that could be highlighted in the design of a RESTful service. RHEx aims to select a single method of implementation to increase the possibility of interoperability and reduce the implementation burden on developers. =UPDATE= An update to a resource can be done in a RESTful manner using either a[| PUT] or [|PATCH] method. A PUT will update the resource if the URI link points to an existing resource by replacing the information. If the resource does not exist, it may be created on the server, as mentioned in the CREATE section. If creation of the resource is not possible an appropriate error response is returned. This method is used by [|hData], [|OData], and [|AtomPub]. [|IHE MHD] does not support an update related action.

When using PUT to update a resource, it is assumed that the entire resource will be sent to the server. That can be inefficient for making small changes in larger resources. Using the PATCH method allows only the changed portions of the resource to be passed to the server. While this approach may appear to be clearly superior upon first reading, it should be noted that it introduces additional complexity between the client and server. There must be an agreed upon representation of a changes to a resource which the client can generate and the server can apply. This is more complex than simply replacing the entire resource with an updated copy. OData supports the PATCH action.

Finally, there is the custom HTTP MERGE method introduced by earlier versions of OData. It behaves similarly to the HTTP PATCH method. =DELETE= The DELETE action will remove the resource bound to the URI link. OData and hData both implement this method at the section and section document level. If implemented at the section path level, OData relies on the server to determine whether cascading rules apply to child resources. hData requires child sections and documents to be removed. IHE MHD does not support a deletion action.

For information on RHEx's __**data content standards**__ follow this link.