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"
        }
    }
}

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.

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.