An API is a client and server communication protocol that simplifies the building of client-side software.

Characteristics of a Well Designed API

A well-designed API should support the following;

  • Service evolution. An API should evolve and add functionality from client applications independently. As it evolves, all the existing client applications should function without any modification with all the functionality being discoverable for use by client applications.
  • Platform independence. This means that regardless of how an API is internally implemented, any client can call it. It requires the use of standard protocols with a way through which the web service and the client agree on the data format to exchange.

 
An API can be designed in any programming language. Similarly, it should be possible for any API to be implemented regardless of the technology used by the consuming developer. However, most APIs make the client libraries available, making it important to take note of the most popular API programming languages.

Designing an API

1. Organizing the API within Resources

This means that for one to develop a successful API, they would need to focus on the business entities that the web API exposes. For example, in a flight booking system, the primary entities might include the passengers and flights. Booking a flight could be achieved by sending an HTTP POST request with the flight information. The HTTP response will indicate if the flight booking was successful or not. The resource URIs should not be based on verbs – the operations on the resource, but on nouns – the resource.

2. Defining Operations in terms of HTTP Methods

There are a number of methods defined by the HTTP protocol. These methods give a semantic meaning to a request. APIs use the following HTTP methods;

  • POST: It creates a new resource at the specified URI. The details of the new resource are provided by the body of the request message. However, POST can also be used in operations that do not create resources.
  • GET: The GET method retrieves a representation of the resource a specified URI. The details of the requested resource are contained in the body of the response message.
  • PATCH: A partial update of a resource is performed by the PATCH method. The set of changes to be applied to the resource is specified in the request body.
  • PUT: The PUT method is responsible for creating or replacing the resource at a specified URI. The resource to be created or updated is specified in the body of the request message.
  • DELETE: This method is responsible for removing the resource at a specified URI.

3. Conforming to HTTP Semantics

There are a number of considerations you should have when designing an API that conforms to the HTTP specification. Some of them include;

Get Methods

A successful GET method is supposed to return an HTTP status code 200 or OK. In case the resource is not found, then the method is supposed to return status code 404, or Not Found.

Media Types

Formats are specified by the use of media types (MIME types) on the HTTP protocol. In the case of non-binary data, most APIs support JSON and XML. The format of the representation is specified by the content type header in a response or a request.

PUT Methods

A PUT method that creates a new resource returns an HTTP status code 201 or Created, just like a POST method. If a PUT method updates an existing resource, it will return status code 204 (No Content) or 200 (OK).

If the method is not able to update an existing resource, then it returns status code 409 or Conflict.

POST Method

A POST method that creates a new resource returns an HTTP status code 201. The location header of the response contains the URI of the new resource while a representation of the resource is found at the response body. However, a POST method might do some processing but fail in creating a new resource. Such a method should return HTTP status code 200 with the results of the operation in the response body. POST methods with no results return an HTTP status code 204 without a response body.

You can read more about HTTP resources and specifications to dig deeper into the relevant resources about HTTP.

Finally, other important things to observe when designing an API include;

  1. Filtering and pagination of data.
  2. Supporting partial responses for large binary resources.
  3. Versioning of the API.

Adopting the OpenAPI initiative specifications.