API Design: Principles and Best Practices

APIs are the front door of any application. They allow clients to get information from your application, or to do advanced things like create objects or perform tasks.

But when you’re creating an API it’s important to be aware of certain conventions. It’s better to stick with known conventions, because these will help people consume your API much more easily.

In this article we’ll cover some of the common questions for designing an API.

When should you return a 404 from an API?

According to the HTTP specification, a web site should return 404 when it can’t find the resource that the user requested. This is because the code 404 means “Not Found” in the HTTP specification.

If you’re developing an API, and you receive an incoming request for an object that does not exist, you can return a 404 status code. For example, if a client makes a request to your API to fetch information about user “jsmith”, but user ID “jsmith” doesn’t exist, you can return 404.

It’s common to also return some meaningful content in the response, like some information that tells the client how to create the resource if it doesn’t exist.

On the contrary, if the object that the user requested can be found, it’s common to return a 200 status code. The code 200 means “OK” in the HTTP specification.

An API returns 404 when a user makes a request for a specific resource, like user “jsmith”, but the resource doesn’t exist on the server. But what should happen when the user wants to find resources matching certain criteria, and no results are returned?

When a client executes a search, but the search returns no results, an API usually doesn’t return 404. This is because the search completed successfully, but 0 results were returned based on the criteria. In this case, the API will return 200 “OK”.

When to use POST or GET in an API?

APIs which are exposed via the web, using HTTP, usually follow the HTTP specifications. This means that the interface, or the surface of the API, that the client interacts with, obeys the rules of HTTP.

The HTTP specifications were originally designed for web sites (or “resources”), but they are now commonly recognised by HTTP APIs, too.

What is a method?

Within the HTTP specification, there is something called a method, which defines an instruction that a web browser gives to a website when it makes a request for a web page. The most common is a GET method, which tells a website that it should return a given document or resource.

The same also applies to APIs. When a client makes a request to an API to get or fetch a resource, it uses the GET method.

There are a couple of other common HTTP methods used with APIs:

The POST method

The POST method accompanies a request when the client wants to send data to the server. This is usually used with APIs when a client wants to create a new resource or object. For example, if your API is responsible for managing addresses, then a client will expect that if it sends a POST request to that API (and includes an Address in the message body), then the API will create a new address.

The PUT method

The PUT method is similar to post, in that it is used when the client wants to send data to the server. However it is slightly different, in that it is interpreted by the server that the client wants to replace the resource or object at that URL, with the new definition.

When to use GET vs PUT.

GET is used to get a resource, POST is used to create a new resource, and PUT is used to replace an existing resource.