Jonathan Tweed

api design: supporting multiple output formats with style

Recently I outlined our API design principles here at MetaBroadcast. One thing I didn’t talk about was our approach to multiple output formats, so I wanted to briefly cover our thoughts on that.

Our basic policy is this. JSON is our preferred format to work with and if we can only do one, we’ll do that. For bigger APIs, like Atlas, which will be used by a wider set of users, we support multiple output formats. Atlas, for example, currently supports JSON, XML and RDF.

So how do we support that in an API? Simple: content negotiation plus a format override.

If the client asks for a specific format in an Accept header our ongoing aim will be to honour that. For users who are unable to set custom Accept headers for whatever reason, be it just debugging in a browser, we will also support overriding the Accept header by adding an extension, eg .json.

We hope to bring Atlas in line with this in API 4.0, which will also mean the URIs will drop the required extension at the end. All part of making us ever more RESTful.

blog comments powered by Disqus