...
The API we are going to expose in our 1.0 pass at web services is entirely about doing CRUD on a data store. We're not dealing with any application flow or business logic. As such we will aim for level "2.5" of the Richardson Maturity Model (described by Martin Fowler here). Resources will include links to URIs of other resources, but the links won't indicate the relationship, rather we're more concerned with exposing our data store. Is this a mistake?not phrased as "rel"s. (We want to support json, we and we're not describing meaningful business-process in those links.)
We will allow Spring to automatically transform our results to json or xml depending on the HTTP request. This probably prevents us from having a proper DAP or XSD.
Is this a mistake?
Standard CRUD pattern as applied to our API
...
URI | Content |
|---|---|
/ws/rest/patient/uuid.json | default representation (not including audit info, including the patient's preferred name but not aliases, etc) |
/ws/rest/patient/uuid.json?v=full | representation including all audit info, all names, all historic addresses, etc. |
/ws/rest/patient/uuid.json?v=fullwithencounters | full representation plus summaries of all the patient's encounters (this can get very big) |
/ws/rest/patient/uuid.json?v=ref | minimal representation, just containing a displayable string, the uri of the default rep, and the uuid |
Question: Is this appropriate? If so, what's the right terminology for this? If not, what alternate approach should we be taking?
Usually the " default " representation of a resource will include "ref"-sized versions of other resources. E.g. the default representation of a patient contains:, while the full representation includes "default"-sized versions of other resources. For example a patient would include
default | full |
|---|---|
{ |
...
person/puuid/address/3350d0b5-821c-4e5e-ad1d-a9bce331e118" |
...
{ |
...
puuid/address/3350d0b5-821c-4e5e-ad1d-a9bce331e118" |
A more relevant example of this is that an encounter might contain 100 observations. The default encounter representation would just include a displayable "weight = 70", whereas the full encounter representation would include full details about the "weight" question (e.g. that it's unit is "kg", its range is 0-250, etc).
...
We also have the idea of "sub-resources". For example a patient has identifiers. These sub-resources will not get a top-level uri, rather:
list all identifiers for the given patient | GET /ws/rest/patient/uuid/identifiers |
list all identifiers for add an identifier to the given patient | POST /ws/rest/patient/uuid/identifiers |
add an identifier to the given patient fetch/update/delete a specific identifier | GET/POST/DELETE /ws/rest/patient/uuid/identifiers/identifier-uuid fetch/update/delete a specific identifier |
We'll lean towards making things top-level resources rather than sub-resources, for example:
...
We've tried to standardize the way we do CRUD via interfaces (Searchable, ( Creatable, Retrievable, Updatable, Deletable, Purgeable), and via a base class that helps reflect these interfaces onto our pre-web-service domain objects: DelegatingCrudResource.