Entry point to REST/HATEOAS API?

Question

I have started designing an API and have decided to have a go at making it conform to REST/HATEOAS. What should the entry point for the API be?

It seems like a common one is GET / but from what I've read it might make more sense logically to use OPTIONS /, as there isn't actually a resource at / for retrieving.

I've given examples of both here, using HAL syntax for JSON as a hypermedia format.

GET /

Request:

GET / HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Date: …
Content-Type: application/json;charset=utf-8
Content-Length: 143

{
    "_links": {
        "self": {
            "href": "/"
        },
        "penguins": {
            "href": "/penguins"
        }
    }
}

OPTIONS /

Request:

OPTIONS / HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Date: …
Allow: OPTIONS
Content-Type: application/json;charset=utf-8
Content-Length: 143

{
    "_links": {
        "self": {
            "href": "/"
        },
        "penguins": {
            "href": "/penguins"
        }
    }
}

Endoskeleton

Why do you think that / doesn't point to a resource? In REST, all URLs refer to resources. In this case, it's a resource to the menu of available links you can follow. – Parma

Answer 1

A response for an OPTIONS request only describes the options for the resource you requested, i.e. /. It's generally much more informative to GET / and then let the link relations per each link in the response body tell you which actions can be taken on the linked resources.

Also, responses to OPTIONS are not cacheable, and that can be very significant, especially when it comes to something static like a menu of links.

Parma

I concur with Jonathan. OPTIONS is not supposed to have a response body, and the only specified detail for it is the response Accept header. Just use GET / and return a JSON response (I negotiate HTML responses too). – Lo

Though I rescinded my original comment about OPTIONS not having a response body (was confusing it with HEAD in my head... no pun intended.) Apparently it's allowed to have a response body (per spec): "The response body, if any, SHOULD also include information about the communication options. The format for such a body is not defined by this specification, but might be defined by future extensions to HTTP." – Parma

Sorry, I didn't mean to imply it ''couldn't'' have a response body ("not supposed to" was badly worded), only that no formats for the response body are specified by HTTP or related IETF standards, therefore opaque response bodies cannot be made use of by generic intermediaries. The Accept header is specified, however. Mark Nottingham makes a good case case against OPTIONS. – Lo

Answer 2

In this simple case, I would suggest the use of the Link header:

HTTP/1.1 200 OK
Date: …
Link:</likeapenguinbutopaque>;rel=penguin;type=image/jpeg

The use of the "rel" attribute allows also to specify a relationship with the target resource referenced by the link. Note that the semantics of "rel" has to be interpreted in the context of the current resource. To illustrate that, lets follow the link. A Picture of a penguin is supposed to be returned, along with the following link:

Link : <>; rel=wing;type=image/jpeg

The "wing" relation is here clear : it is a relation between the current resource, which is a penguin, and its OWN wing (not the wing of another penguin). This is the magic (and the verbosity) of HATEOAS: each link takes its meaning ONLY in a specific resource context. All this is to defeat the temptation to describe all your resource tree in a single document returned at a given occasion while browsing. This would be evil, euh, not HATEOAS...

Note also that HATEOAS is here implemented while exchanging JPEG images, whose media type is NOT hypermedia. The Link header, pervasive and rich enough will do the job. Suppose some of the penguins you have can be updated:

Link: <>;rel=wing;allow=PUT;type=image/jpeg

will signal the point in the precise context of a given updatable penguin.

Dar

This is downvoted, and I have no idea why. To me it seems using the Link header is a very natural thing. – Wachtel