Clear and Concise REST APIs

APIs have users just like apps have users, with the exception that an API’s users are developers. It’s unfortunate how frequently we encounter APIs which are needlessly complex and hard to use. Documentation sometimes is so complicated that it actually makes the API harder to understand rather than easier.

Recently a friend approached me with a question relating to this very subject, “Which do you prefer: api/v1/user/14/ or api/v1/user/?id=14”. I responded that the former was my preferred verbiage and when he asked why I responded, “Semantics”.

Semantics of a Readable API

Certain code reaches a critical mass of complexity that justifies clear comments and detailed documentation. However, when code has more comments than actual code, it becomes impossible to read, and reading other people’s code is a majority of what we, as software engineers, do. Code that is written to be simple and self-documenting will avoid the need for this and can minimize the amount of documentation that you have to write. The same is true for APIs.

By nature, REST lets us do this out of the box. Every REST call is a verb paired with a description of a resource, and often times we can describe that resource in a tight and succinct way that makes documentation a formality rather than a necessity. In the example above my answer was to use:

GET api/v1/user/14/

I said this because this URI says everything we need to know; we know it’s an API and what version of the API is being used. There are bits that the documentation will be necessary to explain in more detail, but the RESTful verbiage of GET, POST, PUT, and DELETE fills in a lot of these missing pieces. The key thing to take away here is that the URI itself is self explanatory. That’s not to say that:

GET api/v1/user/?id=14

isn’t self explanatory as well, but the context of what we’re trying to do gets lost. By separating the user’s ID from the body of the URI it implies that the ID of the user is an afterthought, and just an optional property we might use to describe a user. Parameters are exactly that, and they should be reserved as a means to further describe a resource, not as a requirement to access one.


A clean and simple API should be able to get by with minimal parameters for any GET or DELETE method, and that is especially true of DELETE. The potential to delete the wrong resource increases if your DELETE method required a plethora of parameters.

Parameters are only necessary when you need to describe a resource past it’s basic identifier. This is more applicable to a URI that fetches a collection of resources that share specified properties, rather than one individual resource:

GET api/v1/user/all/?first=scott&company=vokal


I remember listening many years ago to someone saying contemptuously that HTML would never succeed because it was so primitive. It succeeded, of course, precisely because it was so primitive. Today, I listen to the same people at the same companies say that XML over HTTP can never succeed because it is so primitive. Only with SOAP and SCHEMA and so on can it succeed. But the real magic in XML is that it is self-describing.” -- Adam Bosworth, 2004

The beauty of REST is that it is almost entirely self-documenting when used appropriately. In the essence of usability this makes a developer’s life considerably simpler. Clean code and clean APIs should read like a book. Ideally methods should be named in a way that we already know what it is going to accomplish for us, only requiring to read the documentation when absolutely necessary.