How to Design an API

A good API is the one which is easy to use, is consistent in behavior, and provides the information and actions that you need. It should be easy to use. You shouldn’t need tons of documentation as it should be predictable. And it must not break your client’s application with backward incompatible changes.

You can design your API in any way you like. However, before you start coding recklessly, you should ask yourself a few questions:

  • Who will use my API? Will it be just one javascript client or do I expect mobile applications as well? Or, will there be clients who are bound to certain scripting languages?
  • What information do they need?
  • What will they use it for?

The problem is that when you start a project, you might not know the answers to these questions yet. Besides, giving a final answer to the question about the target group can be particularly tricky because over time a number of different client applications may arise. Apart from that, the product itself is likely to evolve significantly over time too.

Our advice is: be prepared!

RESTful API

One way to prepare yourself and your app is to follow the principles of Representational State Transfer Architecture, also known as REST. It is not a standard but rather a guide to the best practices when it comes to how a good interface should be structured.

Although RESTful APIs are not limited to http protocol or web applications, they became popular on the web. This is probably because they fit nicely into HTTP design. So what makes an API RESTful?

  • The server does not store a client’s state
  • Information is provided in the form of resources, each of which has a URI (Uniform Resource Identifier)
  • Standard HTTP methods are used for manipulation with resources:

GET obtains the resource

POST creates a new instance of the resource

PUT updates the existing instance

DELETE, shockingly, deletes the instance

  • Each resource contains references to related resources, if possible

The important thing about these methods is that GET is always safe, it just returns data, and PUT and DELETE are idempotent.

It is also a good practice to follow a simple resource hierarchy. Imagine that you would like to create an app which manipulates a simple database of cars and their owners. Provided we have a base resource /api/, the RESTful api structure could look like this:

/api/owners

  • GET returns all persons (or their ids) in the database
  • POST creates a new person in the database and returns its URI

/api/owners/5

  • GET returns information about the person with ID 5
  • PUT updates information about the person with ID 5
  • DELETE deletes the record for person with ID 5

/api/owners/5/cars

  • GET returns all cars owned by the person with ID 5
  • POST creates a new car entry in the database for the person with ID 5

/api/owners/5/cars/3

  • GET returns information about the third car owned by the person with ID 5
  • PUT updates information about the third car owned by the person with ID 5
  • DELETE deletes the record about the third car owned by the person with ID 5

If you design your API in this way, there is a high probability that a random wandering programmer will understand it without any comprehensive documentation.

There are some limitations, of course. For example, we cannot have a car with more than one owner. We can’t have a car without an owner. And there is no easy way to find the owner of a car if you know some information about the car itself. All this can be overcome, but it is a different story and we hope to cover it in the near future.