REST: Retrieving resources

Michael ScharhagSeptember 1st, 2020Last Updated: August 31st, 2020

0 78 2 minutes read

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
 
{
    "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.

Published on Java Code Geeks with permission by Michael Scharhag, partner at our JCG program. See the original article here: REST: Retrieving resources

Opinions expressed by Java Code Geeks contributors are their own.