Follow These Simple Design Rules to Make Your API More Usable

Our biggest business at SDK Bridge is documenting other companies’ APIs. This has given us a chance to examine a large number of APIs in detail and to see which design patterns have emerged. If you use these design patterns in your own API, then developers are more likely to get up and running quickly.

Which Information Goes Where

There are four common places to put information in an HTTP request: the URL, the headers, the query parameters and the POST/PUT body. Here are some guidelines for figuring out where information should go.

Where What
URL The URL should follow the REST architectural style. It should contain the names of resources and resource IDs only.
Headers The headers are best used for authentication and specifying the format of your data (see below).
Query Parameters   Query parameters should be used to adjust what kind of data to return — for example, pagination (see below) or parameters that filter what data is returned.
POST/PUT body All data that is used to create or modify resources goes in the body of the request.

JSON and XML

Ask the developer users which format they prefer

Although JSON is the most common data format to use, a lot of XML is still being used out there. If you have enough budget, aim to support both formats. However, if you don’t have enough budget, take the time to understand the developers who will be using the API and choose the format they are most comfortable with. If you are supporting both formats, then have this preferred format be used for the default.

If you don’t have enough information to make a choice, then choose JSON, since it considerably more popular for new APIs.

Specify the response format with the Accept header 

There are three common ways to specify which kind of data to return:

  1. The HTTP header named Accept.

    For example: Accept: application/json

  2. A suffix at the end of the URL.

    For example: https://api.example.com/users.json

  3. A query parameter.

    For example: https://api.example.com/users?format=json

The reason that using the header is becoming more popular is that if you are doing a POST or PUT request, then you typically specify the format of the outgoing data using the Content-Type header. Therefore, using a header for specifying the response format is a consistent approach.

Pagination

Often, so much data is returned from a request that developers want to receive the data in pieces. This concept is known as “pagination.” So, if you expect to have 100 objects returned, and you only want five at a time, you can specify a starting index and the number of objects you want returned for that particular request.

These two values are typically query parameters, but there is a great deal of inconsistency in what different companies call them. The most common terms we’ve come across are offset and limit, where offset is the index (zero means the first object) and limit is the number of objects to return. For example, to return data for the 11th through 15th user, you would say:

https://api.example.com/users?offset=10&limit=5

Odds and Ends

Here are a few more design rules to keep in mind:

  • Although whether to have resource names be plural or singular is very much up for debate, it’s more common to make them plural. This allows the URLs to have the same root whether returning data for all resources or returning data for just one resource. For example, this means to return data for a user with ID of 34364, you would use https://api.example.com/users/34364, not http://api.example.com/user/34364.
  • For authentication, use the latest version of OAuth, currently 2.0. OAuth is not trivial to understand, but it’s powerful and flexible, and it’s what nearly all new APIs use.
  • Finally, you may be using your API for purposes other than managing data resources. For example, perhaps a request starts a process on a remote device. Try to follow the spirit of REST by using the appropriate HTTP verb. In this example, POST would start a new process on a remote device, GET would return its status and DELETE would cancel the process.
Peter Gruenbaum Peter Gruenbaum has worked as an API writer to describe APIs for eCommerce, traffic prediction, electric utilities, mobile devices, tractors, and cat humor sites, just to name a few. His company, SDK Bridge, specializes in making APIs more engaging for developers by writing API documentation, sample code, and wrapper SDKs.

Comments