11436 SSO

API Design: Revealing Resource Responses

May 15, 2013

One of the most important elements to consider when designing API response messages is which format you’ll use. Most modern apps prefer JSON and this is what we recommend. Only use XML if there's a strong use case to support it.

With that said, let’s focus on how to model your response message, for both a single resource and a collection of resources, by looking at how three large APIs do this.

Comparing resource response messages

This is a response from Twitter, Foursquare, and Instagram for each of their primary objects. Twitter’s primary object is a tweet, Foursquare’s is a check-in, and Instagram’s is an image.

At the top-level, Twitter is verbose; Foursquare includes meta, notifications, and a response; and, Instagram includes meta and data. Also, note that clicking to open the attributes on Foursquare and Instagram reveals their core object.

Foursquare put their information under response and check-in. We like this but wish they hadn’t buried it under response, since they’ve already separated response from other metadata. Instagram calls their information data, which is basically a throwaway word.

Foursquare does something clever with notifications; imagine every response you get back from their API includes some kind of global state or information that’s changed. The advantage is, you can add the notification information to your API response, so app developers can include and comment on these notifications before placing them in their app.

 "meta": {…},
 "dog": {…}
 "notifications": […],

We recommend a hybrid of Foursquare and Instagram that includes a metadata area, a primary resource, notifications and other global information.

Comparing resource response messages for collections

Now, let’s look at cases with multiple resources. Here, Twitter, Foursquare, and Instagram do basically the same thing, which is to place an object into an array of multiple objects.

Notice that they model their collections on a single resource. Mimicking the single resource creates a sense of predictability; it’s deterministic and you begin to rely on it. Foursquare includes an extra property called source on the single resource that isn’t included with the collection, though the point of this is unclear.

 "meta": {…},
 "dogs": {…} /* include same info as single */
 "notifications": […],

In summary, for a collection of resources, copy the information included in a single resource but make a plural version of the primary resource (e.g., dogs). Try providing a limited subset of the data in the collection to preserve on bandwidth and provide verbosity on drill downs, unless your single resource is huge. Then, trim down the resource that goes into the collection using partial selection. You can see previous versions of these webinar talks for information on partial selections.

Check out our previous posts about partial responses and responses that don’t involve resources.

To join the conversation around APIs, check out the API-Craft Google Group.

Next: Scrutinizing Search Results and Links

Scaling Microservices