HTTP Details
In addition to defining a set of base resources, RfH also provides a RESTful protocol using HTTP. Each resource type has the same set of interactions defined that can be used to manage the resources in a highly granular fashion. Note that it is possible to use the resources in an aggregated fashion without implementing and using the HTTP transactions.
The following logical interactions are supported:
| Instance | |
| read | Read the current state of the resource |
| vread | A version specific read of the resource |
| update | Update an existing resource by it's id |
| delete | Delete a resource |
| validate | Check that the content would be acceptable as an update |
| history | Retrieve the update history for the resource |
| transaction | Support for specific transactions defined on the resource |
| Manager | |
| search | Search the resource type based on some filter criteria |
| create | Create a new resource. The id may be assigned by client or server |
| updates | Get a list of updates to resources of this type, optionally with some filter criteria |
| transaction | Support for specific transactions defined on the resource type |
| conformance | Get a conformance statement for support of this resource type |
| schema | Get the XML schema for this resource ?? |
Note that while these same logical interactions are defined on all resources, applications are not required to implement all of them. The application's conformance statement must say what logical interactions are supported.
Base URL
Each resource lives at a specific location with a known URL which is automatically determined from the id, the resource type, and the base url of the system.
The concept of the base URL is defined because because this specification defines an interface rather than any particular system. The base URL is the address at which all the resources defined by this interface are found. The base URL takes the form of
http(s)://server/path
The path may end with a trailing slash or not. Each resource defined in this specification has a manager that lives at the address "/[type name]" where type name is the name of the type in lower case and plural. So, for instance, the resource manager for the type "Patient" will live at:
http://server/path/patients
Note that applications may need to remove the trailing slash from the base URL when appending the resource address. All the logical operations are provided relative to the address of the resource and defined in these terms below. Note that this means that given the address of any one resource on a system, the correct address for all the other resources may be determined. However since application URLs may change, and because local configuration may dictate that the provider of a resource is different to that claimed by any particular provider or consumer, applications should be adroit at replacing base URLs.
HTTP Status Codes
For all interactions, if the requested resource is returned as requested, the HTTP status 200 OK should be used (except for "create" where the status code should be 201). If the resource is not known, the server should return an HTTP status code 404 Not Found. Other HTTP errors may be returned as appropriate.
A redirect should only be used to redirect to a new base URL, not to indicate that the master id has changed. The reason for this has nothing to do with http, but because the ids are treated as stable references elsewhere and used for matching. Changing an id will cause problems with this matching.
Security
For this specification, normal HTTP security and authentication rules apply. The base URL will specify whether SSL is required. HTTP authentication may be required by the provider. It is a matter of application requirements and local configuration whether all interactions run under the account of a trusted system user, or whether each interaction runs under the account of the individual user.
XHTML
The master resource format is xml, as defined throughout the specification. All the transactions as described use the XML format. Additionally, servers must (can?) provide an XHTML view of a resource for the read operation (and vread if it is supported). The client requests an XHTML view by substituting .htmll for .xml. The XHTML view must be generated from the data in the resource, and must contain enough of the data to allow a clinically safe human interpretation of the resource. The XHTML rendition must be valid narrative.
read
The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET operation as shown:
GET [baseurl]/[resourcetype]/#{id}.xml
This returns a single instance with the content that which is specified for the resource type. This url may be accessed by a browser. The possible values for the id itself are discussed in the Resource Type. As noted above, the read operation may also request an html rendering of the resource:
GET [baseurl]/[resourcetype]/#{id}.htmll
vread
The vread interaction preforms a version specific read of the resource. The interaction is performed by an HTTP GET operation as shown:
GET [baseurl]/[resourcetype]/#{id}/version-#{vid}.xml
This returns a single instance with the content that which is specified for the resource type. This url may be accessed by a browser.
The version id is an opaque identifier that conforms to the same format requirements as a resource id. The id may be found by performing a history operation (see below) or from a version specific reference in a content model. The vread interaction should succeed even after deleting a resource as long as a correct version identifier is provided. Like the read operation, the vread operation supports JSON and XTML.
update
The update interaction changes an existing resource. The interaction is performed by an HTTP PUT operation as shown:
PUT [baseurl]/[resourcetype]/#{id}.xml
In order to be accepted, an update operation may need to include a transaction section. See Transactions for more details. To get a copy of the newly updated resource (which may not be the same as that submitted) returned with the acknowledgement , use ?reload=true on the request.
Servers may also choose to accept a JSON format as well. In this case, the extension is .json. Servers that choose to accept JSON must still support the master xml format.
delete
The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE operation as shown:
DELETE [baseurl]/[resourcetype]/#{id}.xml
In order to be accepted, an delete operation may need to be accompanied by a transaction section. See Transactions for more details. Servers may refuse to delete a resource, depending on audit requirements. If a server refuses to delete a resource on principle, then it should return the status code 405 method not allowed. If the server refuses to delete a resource because of reasons specific to that resource, such as referential integrity, it should return the status code 412 Expectation Failed.
validate
The validate interaction checks whether the attached content would be acceptable as an update to an existing resource. The interaction is performed by an HTTP PUT operation as shown:
POST [baseurl]/[resourcetype]/validation
POST [baseurl]/[resourcetype]/validation/#{id}
In the first case, the content is checked against the general specification and against the conformance profile that applies to the application. In the second case, additional instance specific things such as referential integrity and update rules are applied as well. In the second case, a transaction section may be required to trigger the correct update rules. The return content has status 200 OK if the content validates ok, or 412 Precondition Failed, with the following content:
<validation xmlns="...">
<error type="string">General error message</error>
<messages type="list">
<message>
<path type="string">[Optional] xpath to the issue</path>
<error type="string">Description of the problem</error>
</message>
<messages>
</validation>
history
The history interaction retrieves the history of the resource. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/#{id}.xml?view=history[&content=true]
The return content has the following content:
<history xmlns="...">
<events type="list">
<event>
<date mand type="datetime">When the event happened on the server</date>
<id mand type="id">[Optional] The id that identifies this version</date>
<transaction opt type="Transaction">[Optional] Transaction details</transaction>
<content opt type="[resourcetype]">
Content for the version referenced
</content>
</event>
<events>
</history>
The content element will only be filled out if the content=true parameter is specified in the request, and if the server is prepared to do so (can be difficult because xml id attributes may have to be rewritten). The server must declare if it is willing to provide the content in it's conformance statement.
search
This interaction searches the resource type based on some filter criteria. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/search.xml
The return content has the following content:
<[resourcetype] xmlns="...">
<[resource]>
<!-- Content for resource -->
</[resource]>
</[resourcetype]>
For example, with patient, the response would look like this:
<patients xmlns="...">
<patient>
<!-- Content for patient -->
</patient>
<patients>
The search results are divided into a number of pages using offsets. It is at the discretion of the server how many results to return, though the client may request a particular number of a count parameter. If the client wishes for more results, it should use the n parameter. More generally, the client uses parameters to narrow the search and increase it's usefulness. The following table summarises ths search parameters:
| n | Starting offset of the first record to return in the search set |
| count | Number of return records requested. The server is not bound to conform. |
| [path] | a value to match in the content model. |
The path is a reference to an element in the content model. The general form is [name].[name] etc. So to search by a patient telephone number, the parameter would be contacts.contact.value, and the value of the parameter would be tel:[#]. Which parameters to support is at the discretion of the server. (TODO: should the client be able to know?). Additional parameters may be defined for individual resource types.
create
The create interaction creates a new resource. The interaction is performed by an HTTP POST operation as shown:
POST [baseurl]/[resourcetype].xml
In order to be accepted, a create operation may need to be accompanied by a transaction section. See Transactions for more details. To get a copy of the newly created resource (which may not be the same as that submitted) returned with the acknowledgement, use ?reload=true on the request.
If the client does not provide an ID, the server will assign an id, and return it in the HTTP location header:
Location: [baseurl]/[resourcetype]/#{new-id}.xml
in addition to returning the id in the xml content if requested.
The client can also submit the content with an id included. If it does, the server must either honor the requested id, or return a 409 Conflict if a resource already exists by that id, or a 403 Forbidden if it will not honor client ids at all
updates
The updates interaction retrieves a list of changes to the resource type. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/updates.xml
The return content has the following content: TODO: what? rss? atom? custom? (and review the url above)
The client can use parameters to narrow the search and increase it's usefulness. The following table summarises ths search parameters:
| since | The time from which to return new updates |
| [path] | a value to match in the content model. |
See search above for details of the [path].
transaction
The transaction interaction provides support for specific transactions defined against the resource by this specification. The transaction interaction is supported on both individual resources and the type:
POST [baseurl]/[resourcetype]/transaction
POST [baseurl]/[resourcetype]/transaction/#{id}
The content model of the request and response will be specified when the possible transactions are defined throughout this specification.
conformance
The conformance interaction retrieves the application's conformance statement for the resource. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/conformance.xml
For the return content, see Conformance. If a 404 Unknown is returned, no other interactions are implemented.
schema
The schema interaction retrieves a w3c schema for the resource. The interaction is performed by an HTTP Get operation as shown:
GET [baseurl]/[resourcetype]/schema.xsd
The return content is a W3C schema that describes the resource. The schema does not have to be the one defined with this specification; it can eliminate elements not supported by the server, and explicitly define extensions supported by the server. However the xml format it describes must be consistent with the rules defined in this specification.
Intermediaries
The HTTP protocol may be routed through an HTTP proxy such as squid. Such proxies are transparent to the applications, though implementors should be alert to the effects of rogue caching.
Interface engines may also be placed between the consumer and the provider; these differ from proxies because they actively change the content and/or destination of the HTTP exchange. Such agents are allowed, but are bound to the conform to this specification. In order to assist with troubleshooting, any agent that modifies an HTTP request or Response content must add a stamp to the HTTP headers like this:
request-modified-[identity]: [purpose] response-modified-[identity]: [purpose]
The identity must a single token defined by the administrator of the agent that will sufficiently identify the agent in the context of use. The header must specify the agents purpose in modifying the content. End point systems must not use this header for any purpose; it's aim is to assist with system troubleshooting.
© 2011 