Building an API

As a developer, you will eventually need to create or work on an API. Why? Because they are so hot right now! But besides that, they allow your customers or any other consumer do some amazing things. I am sure you have heard the old saying “Cash is King”. In the software arena I believe “Data is King” and API’s serve as a vehicle for that data. REST (representational state transfer) is an elegant way to represent your data in an API. Let’s take a look at the model of REST introduced by Leonard Richardson which is referred to as the Richardson Maturity Model. The levels (described below) help illustrate RESTful API approach and give some context of achievements to strive for true REST. One of the principal authors of REST, Roy Fielding, will tell you himself that level 3 (Hypermedia) is a requirement to call your API a REST API. Let’s look at the Richardson Maturity Model to get an illustration of what a REST API should achieve.

Level 0 – Use of HTTP Protocol
This level is the basic use of HTTP to transport the information from the client to the server. Nothing from this level actually separates REST from other API approaches but the definition of the transport protocol is essential.

Level 1 – Resources and Endpoints
This is where REST starts to take form. The idea is to not have a single endpoint for all calls but to have one for each resource. A resource would be the model in your business domain and represent the items an external system would want to create, retrieve or update.

Level 2 – Using HTTP Verbs and Responses
The idea behind this level is to utilize the HTTP verbs that are present in order to show intent. For example, if you want to get all the items of a particular resource you would call the URI for that resource with a GET verb. Likewise, if you want to create a new instance of a resource you would call a POST to the resource’s URI. Again, the verb is used to show intent.

The response from the API uses HTTP status codes to give back status. For example, if you used a POST to create a new instance of a resource you would expect to get a 201 (Created) back with the location being defined for the exact URI of that resource instance. The response would also contain a representation of that instance that was just created to save on a round trip back to the server.

Level 3 – Hypermedia
This is the level that is left out by a lot of APIs in the wild today. It is the level that helps with discoverability. This provides a few benefits- the biggest of which is flexibility. If the consumers of the API used the links to lookup related resources, the architects of the API could in theory change out the URIs as long as they left the top level or entry points alone.

This level also gives developers the ability to explore the API by clicking on the links that are provided as they drill down into resources. It’s a way to introduce newer features to developers of the API that can be discovered through hypermedia.

Here are a few things that should be considered in your API architecture:

  • Support JSON as the content type. All the cool kids are using JSON! (XML can also be supported)
  • Represent all resources using Nouns in the plural form with actions represented with HTTP Verbs. (GET, POST, PUT, DELETE and PATCH)
  • Versioning: Implement versions to allow future releases to be adopted at the developers pace.
  • Usage Tracking: Usage metrics can help you identify use of certain endpoint and notify consumers of any major changes. They also allow you to impose limits in the future if necessary.
  • OAuth Security: Single sign on is a must nowadays.
  • Find a documentation tool and use it early. Apiary has been my tool of choice. Besides beautiful documentation, it allows you to test and do some rapid development.

Creating your first API is exciting and fun so enjoy the journey. Don’t get stuck on the details but stay true to the principles that make an API great.


Also published on Medium.