REST: Retrieving resources

Retrieving resources is probably the simplest REST API operation. It is implemented by sending a GET request to an appropriate resource URI. Note that GET is a safe HTTP method, so a GET request is not allowed to change resource state. The response format is determined by Content-Negotiation.

Retrieving collection resources

Collections are retrieved by sending a GET request to a resource collection.

For example, a GET request to /paintings might return a collection of painting resources:

Request:

GET /paintings
Accept: application/json

Response:

HTTP/1.1 200 (Ok)
Content-Type: application/json

[
    {
        "id": 1,
        "name": "Mona Lisa"
    }, {
        "id": 2
        "name": "The Starry Night"
    }
]

The server indicates a successful response using the HTTP 200 status code (see: Common HTTP status codes).

Note that it can be a good idea to use a JSON object instead of an array as root element. This allows additional collection information and Hypermedia links besides actual collection items.

Example response:

HTTP/1.1 200 (Ok)
Content-Type: application/json

{
    "total": 2,
    "lastUpdated": "2020-01-15T10:30:00",
    "items": [
        {
            "id": 1,
            "name": "Mona Lisa"
        }, {
            "id": 2
            "name": "The Starry Night"
        }
    ],
    "_links": [
        { "rel": "self", "href": "/paintings" }
    ]
}

If the collection is empty the server should respond with HTTP 200 and an empty collection (instead of returning an error).

For example:

HTTP/1.1 200 (Ok)
Content-Type: application/json

{
    "total": 0,
    "lastUpdated": "2020-01-15T10:30:00",
    "items": [],
    "_links": [
        { "rel": "self", "href": "/paintings" }
    ]
}

Resource collections are often top level resources without an id (like /products or /paintings) but can also be sub-resources. For example, /artists/42/paintings might represent the collection of painting resources for the artist with id 42.

Retrieving single resources

Single resources retrieved in the same way as collections. If the resource is part of a collection it is typically identified by the collection URI plus the resource id.

For example, a GET request to /paintings/1 might return the painting with id 1:

Request:

GET /paintings/1
Accept: application/json

Response:

HTTP/1.1 200 (Ok)
Content-Type: application/json
Last-Modified: Sat, 16 Feb 2021 12:34:56 GMT

{
    "id": 1,
    "name": "Mona Lisa",
    "artist": "Leonardo da Vinci"
}

If no resource for the given id is available, HTTP 404 (Not found) should be returned.

The Last-Modified header

The previous example also includes a Last-Modified header which tells when the resource has been last modified.

This gives the option for conditional requests using the If-Modified-Since and If-Unmodified-Since headers. The If-Modified-Since header helsp to support caching while If-Unmodified-Since can be used to avoid the lost-update problem with concurrent resource updates.

According to RFC 7232 (conditional requests):

An origin server SHOULD send Last-Modified for any selected representation for which a last modification date can be reasonably and consistently determined, since its use in conditional requests and evaluating cache freshness (RFC7234) results in a substantial reduction of HTTP traffic on the Internet and can be a significant factor in improving service scalability and reliability.

Interested in more REST related articles? Have a look at my REST API design page.