A recommended REST implementation pattern

Representational State Transfer (REST) is a increasingly popular style of interface design for services exposed via HTTP. But what is the best practice for creating a concrete REST implementation? JAREST is a reusable pattern you may use to design your own REST-compliant interface.

It has a specific format for the URIs

The URI format includes a name of the environment (production, test, ...) and a major version number. JAREST specifies the location of the API schema file and the format of resource paths.

It has a specific format for the message bodies

JAREST specifies constraints on the format of the request and response message bodies and how the server should behave when then client sends an incomplete resource representation with POST or PATCH. It specifies the format of links. Unlike other proposals, JAREST does not specify a special "links" property under which all links are enumerated.

It standardizes the way resources are embedded in other resources

A resource representation may have a link to another resource, but it may also include the representation of that other resource completely or partially. JAREST specifies how to deal with partially embedded resources. It specifies the format of links. Unlike other proposals, JAREST does not specify a special "links" property under which all links are enumerated.

New resources are created by using a template

To create a new JSON resource, JAREST demands that the clients first get a template, then fill in the template and then post it. To get a template, a link called "new" is available in the parent resource. The template contains all properties we are allowed to post, plus one link called "create". This allows the server to dynamically determine default values for the properties.

JAREST has a clear view on resource versioning

JAREST specifies how to deal with major and minor versions and how to support old versions for clients that are not ready to move to the new versions.

JAREST has a clear view on HATEOAS

Every REST interface must apply the principle of 'hypermedia as the engine of application state'. JAREST acknowledges that, but claims that this requirement is fulfilled if only the REST interface allows the construction of a HATEOAS-compliant client in theory, while in practice, we usually choose to build a client that is aware of the resource structure. Still, JAREST puts serious restrictions on client knowledge, in particular that business rules should not be hard-coded in the client.