11436 SSO

API Design: Representing Actions and Metadata in Responses

May 22, 2013

In our previous discussions about API design, we outlined an API design strategy, discussed security measures, and the various elements that go into response messages, including search results and links. Now, let’s explore how we can represent actions and metadata in a response message.

How can we represent actions in a response message?

When we say actions, we are talking about state transitions that are coming from a particular resource. Let’s look at some examples.


PATCH /repos/:owner/:repo 


name: Required string

description: Optional string

GitHub’s API uses an "out-of-band" approach. The example above is an update to a repository. Their documentation includes the HTTP method, the URI template, and the input fields to use, but it takes us away from intuitively deciphering the message.

Form-based API

"actions": [{
  "name": "edit-repo",
  "method": "PATCH",
  "href": "https://api.github.com/repos/kevinswiber/siren",
  "fields": [ { "name": "name", "type": "text" },
    { "name": "description", "type": "text" }

The alternative is an HTML form-based approach. Inline form-style actions provide greater insight to developers exploring the API via HTTP.  Siren’s form-based API does exactly what GitHub’s approach does but inline.

We recommend using an inline HTML form-based approach

If you are familiar with HTML, you have a form tag, a method (with a URL to execute the method), and a list of fields. Moving towards the inline HTML form-based approach allows hidden fields, which allows the server to maintain control of the preferred method, href, and fields. This approach allows for easier inclusion of hidden field values the server deems necessary. That means you can exchange client data and keep a stateless nature on your API server.

To illustrate this, when an action comes back in my HTTP response, my code will parse it. Then, I can introspect my properties and build my form so the method (e.g., PATCH) goes back to this href.

How do we represent metadata in a response?

Let's look at examples from Flicker and Dropbox.

Flicker API (inline)


Dropbox API

  "size": "225.4KB",
  "rev": "35e97029684fe",
  "bytes": 230783,
  "modified": "Tue, 19 Jul 2011 21:55:38 +0000",
  "path": "/Getting_Started.pdf",
  "is_dir": false,
  "icon": "page_white_acrobat",
  "root": "dropbox",
  "mime_type": "application/pdf",
  "revision": 220823

Flickr includes metadata, such as number of views, server, and favorites inline with the data representation, while Dropbox has a separate metadata resource that returns its metadata. Actually, both these options are good.  If the amount of metadata is relatively small, including it inline, rather than creating a brand new resource, makes sense.

When there’s many metadata, like in the case of Dropbox, adding a separate resource makes sense. This is especially true when metadata is important to your API consumers.  This might be a good topic for a future discussion on API modeling, since metadata can also include response times, pagination counts, and so on.

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

Next: Harnessing Hypermedia Types

API Management Decision-Making Kit

Next Steps


Resources Gallery