REST / HATEOAS API entry point?

Question

I started developing the API and decided to make it consistent with REST / HATEOAS. What should be the entry point for the API?

It seems like a common GET / , but from what I read, it might logically make sense to use OPTIONS / , since there really is no resource in / to retrieve.

I gave examples here using the HAL syntax for JSON as a hypermedia format.

Get /

Request:

 GET / HTTP/1.1 Host: example.com 

Answer:

 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 

Answer:

 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

The response for the OPTIONS request describes only the parameters of the requested resource, i.e. / . It is usually much more informative for GET / , and then let the link relationships for each link in the response body tell you what actions can be taken for related resources.

In addition, the answers to OPTIONS not cacheable, and this 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 using the Link header:

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

Using the rel attribute also allows you to specify a link to the target resource referenced by the link. Note that the semantics of "rel" must be interpreted in the context of the current resource. To illustrate this, give a link to the link. The penguin image is supposed to be returned along with the following link:

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

The wing relationship here is clear: this is the relationship between the current resource, which is a penguin, and its wing OWN (and not the wing of another penguin). This is the magic (and verbosity) of HATEOAS: each link only makes sense in the specific context of the resources. All this is to defeat the temptation to describe the entire resource tree in a single document that is currently returned during viewing. That would be evil, hey, not HATEOA ...

Please note that HATEOAS is implemented here when exchanging JPEG images whose media type is not hypermedia. The Link header, widespread and rich enough, will do the job. Suppose some of your penguins can be updated:

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

will signal a point in the exact context of this updated penguin.