Question

Here are a couple of standard URLs of a RESTful API.

• http://api.example.com/user/123
• http://api.example.com/users

The first retrieves a single user, the second – a collection of users (let’s say 20).

What is the “REST” term to refer to these URLs? Is it correct to refer to them as resources? If the first is a resource, should the second be a resource collection or should it rather be just a resource of type collection?

Answer 1

Every URI on a RESTful application is a resource, this description is sufficient.

Resources that link to several resources of the same type may be called collections, but there is no official name for that. Every resource, being a collection or not, can have links.

Links between resources are the Hypermedia part of a RESTful system. Recently, a new term came up for this: HATEOAS, Hypermedia As The Engine Of Application State.

It’s a common good practice to name collections in plural, so your /users/ sample seems correct. The user 123 is a child of the users collection, so it may be better to put it under /users/123 in plural as well.

A RESTful, HATEOAS application would respond a list of links on /users/ pointing to individual resources. Something like:

{
    "links": [
        {
            "href" : "/users/123/"
            "title" : "Alexandre Gaigalas"
        },
        {
            "href" : "/users/125/"
            "title" : "John Doe"
        },
    ]
}

Or in XML:

<link href="/users/123" title="Alexandre Gaigalas">
...

Additional information apart from the links object in JSON or tags in XML may be provided.

These links stabilish a RESTful hypermedia relationship between resources. The samples I gave are mostly hierarchical between collections and individuals, but other types of links may be declared:

<link href="/users/123/picture.jpg" title="Alexandre Gaigalas avatar" rel="picture">

The collection terminology was created mostly for abstracting a RESTful implementation in programming languages, so developers can group and manipulate groups of similar resources more easily.

When present, query string parameters identify different resources as well, so /users/?since=2009 is a different from /users/. They’re both different resources, although very similar ones.

Fragment identifiers, even though not sent to the server anyway, are considered different resources as well, so /users/123#bio is different from /users/123.

If possible, a more meaningful pagination is better. Page numbers are hard to handle RESTfully because they change a lot. If there is a frequently updated collection (like a list of StackOverflow questions for example), the page one frequently changes and the user may loose items changing from page 1 to page 2. Most collections can be paginated by date or alphabetically. Incremental page numbers aren’t wrong, but there are better mechanisms.