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.