REST Responses are Views of Data

, a 6-minute piece by Dev Mukherjee Dev Mukherjee

RESTful services use semantic URLs to refer to entities or collections of entities. Contrary to how many software frameworks implement endpoints, more often than not REST services deliver views of entities, not the entity itself.

Consider the following use cases for an application's user interface:

Subject to amount of detail, for the first use case we would send back a list of albums and optionally a summary of tracks. Since we already know the artist, including artist information would add unnecessary extra weight to response size.

{
    "name": "Journeyman",
    "release_date": "7 November 1989",
    "track_count": 12,
    "length": "56:35",
    "tracks": [
        {
            "number": 1,
            "name": "Pretending"
        },
        {
            "number": 2,
            "name": "Anything for Your Love"
        }
    ]  
}

The later could do with scanty information on albums, but include the artist data in line.

{
    "albums": [
        {
            "name": "Journeyman",
            "release_date": "7 November 1989",
            "artist": {
                "name": "Eric Clapton",
                "solo": true,
                "date_of_birth": "30 March 1945"
            }
        },
        {
            "name": "...But Seriously",
            "release_date": "24 November 1989",
            "artist": {
                "name": "Phil Collins",
                "solo": true,
                "date_of_birth": "30 January 1951"
            }
        }
    ]
}

Irrespective of the persistent storage in use, it makes sense to store Artists and Albums separately, with references that relate the two.

The above use cases demonstrate that interfaces present views of data. Effective APIs should assist client applications by delivering useful views on the stored entities.

Next Up: a 1-minute piece by Dev Mukherjee Dev Mukherjee

Wine Folly - The Essential Guide to Wine

Read more