API Design: Features Of Good REST APIs

Saturday, 06 October 2018

API's allow software applications to talk to each other without human intervention. Before that can happen the API will need to be integrated with the consuming application. Some API's are easy to integrate and some just aren't. This blog post will introduce some of the characteristics of a good API.

Well Documented

First and foremost, API's should always include solid documentation. Documentation should be targeted at the developer that will be consuming the API so it's key that API developers know the intended audience. Having good documentation will decrease the amount of time a developer will spend working on integrating the API with the consuming application. As a bare minimum, your API documentation should have the following features:

  • A clear explanation of what each method call does
  • Include the URL, HTTP method, each parameter including the type and whether or not they are required
  • Real world examples showing how to call an API endpoint with a sample response


It's important that API's are secure to protect them from attacks. Only authenticated users/clients should be allowed to make requests to an API endpoint. There are many methods you can use to secure your API, however, OAuth (Open Authorization) is the most popular method today. Other methods include the following:

  • Using encrypted API keys
  • Basic HTTP authentication

It is also key that SSL is used with all methods. By always using SSL any authentication credentials sent along with requests will remain protected. These methods of security, including OAuth, will be covered in a later post.


When building an API that will be used by clients that are not in your control, versioning is an essential feature. Versioning allows you to make required changes to your API without breaking an existing client integration. API versions only need to be changed when a breaking change is made. Breaking changes include the following but are not limited to:

  • Changing the response structure or type
  • Removing an existing endpoint
  • Adding a new required parameter

There is no specification on how to version an API but there are three common approaches to versioning.

  • URI Versioning - The version is included as part of the URI as a prefix or suffix to the resource being accessed. Most API providers follow the V[x] syntax but this is not required as the version can be any string. This is probably the most common method of versioning an API. e.g. /v1/Cars
  • Using a custom request header - One of the major benefits of specifying the version in a custom request header is that this allows you to preserve the URIs between versions.
  • Using a query parameter

Good Errors

To give users of your API the best experience it's necessary to provide good error messages to help people know what to do when things go wrong. A good error message will tell the consumer two things, what is wrong & how to fix the issue.
Tips on providing good error messages:

  • Always use the standard HTTP status codes where applicable
  • Error messages should be clear and specific to the context e.g. 400 bad request vs 400 bad request with body  “request is missing required ID”
  • If possible include links where developers can find more info about the issue

These are just some of the features good API's will have. Let me know what other important features API's have in the comment section below.