For my work I need to find out what is necessary for a modern REST-API. In theory, I want to get a global view about the glory of REST “Richardson Maturity Model“.

First, I want to thank Matthew Weier O’Phinney for the documentation about his PhlyRestfully module for the Zend Framework 2. PhlyRestfully implements RESTful JSON APIs in Hypermedia Application Language (HAL). He also explain things under the hood.

It should be forgiven, that I will use many words from his documentation for a overview in this lazy article. 🙂

HAL Primer
HAL, short for “Hypermedia Application Language”, is an open specification describing a generic structure for RESTful resources.
– expose resources
– via HTTP, using HTTP verbs to manipulate them
– and provide canonical links to themselves, as well as link to other, related resources

Hypermedia Type
HAL presents two hypermedia types, one for XML and one for JSON. Typically, the type is only relevant for resources returned by the API, as relational links are not usually submitted when creating, updating, or deleting resources. The generic mediatype that HAL defines for JSON APIs is “application/hal+json”.

For JSON resources, the minimum I must do is provide a “_links” property containing a “self” relational link. As an example:

    "_links": {
        "self": {
            "href": ""
    "id": "1",
    "name": "Homer Simpson"

Interacting with HAL
a request, using the Accept header with a value of “application/json” or “application/hal+json” (the latter really isn’t necessary, though).
If POST’ing, PUT’ting, PATCH’ing, or ‘DELETE’ing a resource, you will usually use a Content-Type header of either “application/json”, or some vendor-specific mediatype you define for your API; this mediatype would be used to describe the particular structure of your resources without any HAL “_links”. Any “_embedded” resources will typically be described as properties of the resource, and point to the mediatype relevant to the embedded resource. The API will respond with a mediatype of “application/hal+json”.

How do I reporting errors?
REST advocates indicate that HTTP response status codes should be used, but little has been done to standardize on the response format.
This mediatype, “application/api-problem+json” is via the IETF, and actually also includes an XML variant.
– problemType: a URL to a document describing the error condition (required)
– title: a brief title for the error condition (required)
– httpStatus: the HTTP status code for the current request (optional)
– detail: error details specific to this request (optional)
– problemInstance: a URL to the specific problem occurrence (e.g., to a log message) (optional)

HTTP/1.1 500 Internal Error
Content-Type: application/api-problem+json
    "problemType": "",
    "title": "Internal Server Error",
    "detail": "Status failed validation",
    "httpStatus": 500

Whitelisting HTTP Methods
should I provide with the via HTTP method, OPTIONS, and a related HTTP response header, Allow. Calls to OPTIONS are non-cacheable, and may provide a response body if desired. They should emit an Allow header, however, detailing which HTTP request methods are allowed on the current URI.

OPTIONS /api/users

with it’s response:

HTTP/1.1 200 OK
Allow: GET, POST

Content Negotiation
Should a client inform the server what media types it understands. More precisely, the client provides an Accept HTTP header that lists acceptable media types and associated quality factors. It can choose the best representation of a resource. see:

the accept definition in our request should be: “*/json”

Service Versioning via Content Negotiation
Inevitably there will come a time when an API requires a change to its returned or expected representation that will cause consumers to break and that breaking change must be avoided. Versioning the API is the way to avoid breaking clients and consumers.

# Request
Accept: application/json; version=1
# Response
HTTP/1.1 200 OK
Content-Type: application/json; version=1
{"id":"12345", "name":"Homer Simpson"}

Metadata Mapping
Do I need a low-level, configurable mechanism that ensure:
– resources have the correct “self” relational link
– resources are extracted to a JSON representation correctly
– that embedded resources are rendered as embedded HAL resources

The metadata map maps a class to a set of “rules” that define whether the class represents a resource or collection, the information necessary to generate a “self” relational link etc.

CRUD, Verbs, and Actions

GET /users              index   display a list of all users
GET /users/new          new     return an HTML form for creating a new user
POST /users             create  create a new user
GET /users/:id          show    display a specific user
GET /users/:id/edit     edit    return an HTML form for editing a user
PATCH/PUT /users/:id    update  update a specific user
DELETE /users/:id       destroy delete a specific user

resource names are in plural

There two uses for ETags (Entity Tags):
– Conditional GET (the so-called “cacheing mechanism”)
– Concurrency Control (resolves “Lost Update Problem”)