When talking about REST APIs, one of the frequent questions pertains to the benefits of using an Accept header, rather than file extensions, to do content negotiation. Often, the benefits of the Accept header don’t seem to outweigh the familiarity of file extensions.

An Example Application

Let's say I have a small command line application that prints out issue information from an issue tracker corresponding to a local feature branch in Git. Usage may look like so:

$ git-issue-branch some-issue
Found a bug

I'm having a problem with this.

I could store the information in SQLite with a schema like this:

CREATE_TABLE issue_branches (
   id integer primary key,
   branch text,
   issue_uri text       
);

The script to do this would have very simple logic: lookup the issue_uri from the db, do an HTTP GET, parse the response, and print the title and body of the issue.

Transitioning the application

Let's say that this application uses an XML API, but I'd rather use JSON. The incidental complexity associated with this change depends on how the server handles representations. If the API honors Accept headers, this is easy: the client changes a header.

If the API doesn't honor these headers and instead relies on file extensions, things become more complex: the client developer needs to parse the URIs, replace the old extension with the new extension, test the URIs to make sure they are well-formed and functional, and perform data migration.

Client Simplicity

Allowing file extensions to determine the content type is fine, and it can be helpful in environments that don't allow setting headers. By allowing only file extensions to determine the content type, though, the API designer forces a more complex implementation on the client developer.

As API designers, we often focus on designing for a specific client, when we need to focus more on allowing the client developer decide implementation details.