How should a server respond to a GET request for a resource that is an unbounded collection in a REST API? - rest

Question

Consider the following URIs where the server returns a representation corresponding to the nth Fibonacci number.
GET /fib/0 ==> { value: 0, _links: { next: { href: '/fib/1' } } }
GET /fib/1 ==> { value: 1, _links: { next: { href: '/fib/2' } } }
GET /fib/2 ==> { value: 1, _links: { next: { href: '/fib/3' } } }
...
GET /fib/73 ==> { value: 806515533049393, _links: { next: { href: '/fib/74' } } }
... etc ...
Given the constraints of a strict interpretation of REST, what should the server return when it receives the following request?
GET /fib

Answer 1

Wikipedia says to return the collection members as links, optionally with details of each member. Obviously you cannot return the whole collection in this case, because it is unbounded. The RESTful APIs we have built with large collections will return the collection paginated. I don't know if this would be a useful thing to return in your use case, but I see you are using HAL, so if you were to, it could look like this for linked data:
{
"_links": {
"self": { "href": "/fib?page=2" },
"next": { "href": "/fib?page=3" },
"prev": { "href": "/fib?page=1" },
"fibs": [
{"href": "/fib/4" },
{"href": "/fib/5" },
{"href": "/fib/6" }
},
}
or this for embedded:
{
"_links": {
"self": { "href": "/fib?page=2" },
"next": { "href": "/fib?page=3" },
"prev": { "href": "/fib?page=1" },
},
_embedded: {
"fibs": [
{
"_links": {"self": "/fib/4" },
"value": 2
},
{
"_links": {"self": "/fib/5" },
"value": 3
},
{
"_links": {"self": "/fib/6" },
"value": 5
}
}
}
You can see a similar example to this in the HAL spec: https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-00#section-6
If the user doesn't specify the page query string param, we return the first page.
If returning the collection (paginated or in it's entirety) doesn't make sense, then I would recommend returning a 405 Method Not Allowed HTTP response code. If you cannot insert items (POST) into the collection either, then maybe return the same 405 response for that too.

Answer 2

The server should return a resource that is represented by /fib or 404 if no such resource is defined/exists. What the resource actually IS depends on the domain and requirements of your application.

Answer 3

According to W3's Dereferencing HTTP URIs, because I cannot return an infinite sequence, it looks like I should return an HTTP 303 - See Other redirect to another URI (e.g. /fib/Information) which contains additional related information about the Fibonacci sequence such as a human-readable description, an algorithm to compute it, or an RDF description of the aggregation. I should support content negotiation to allow consumers to select an appropriate representation.