Make Your APIs Trivially Expandable

When designing an API, don’t do this:

// QUERY: GET /users/search?query=bob

// RESPONSE:
[
    {
        "first_name": "Bob",
        "last_name": "Dole"
    },
    {
        "first_name": "Kevin",
        "last_name": "Bobson"
    }
]

Any change in requirements will break this API, and potentially any client applications using it.

Instead, nest your information one level, so expansion is trivial.

This:

{
    "results": [
        {
            "first_name": "Bob",
            "last_name": "Dole"
        },
        {
            "first_name": "Kevin",
            "last_name": "Bobson"
        }
    ]
}

Can easily be expanded into this, without breaking old client code:

{
    "batch_size": 2,
    "total": 1000,
    "results": [
        {
            "first_name": "Bob",
            "last_name": "Dole"
        },
        {
            "first_name": "Kevin",
            "last_name": "Bobson"
        }
    ]
}
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s