Best Practices in API Design

How to design a good API is a question that comes from many teams that try to create perfect REST API. This article shows briefly some of good rules to remember and advice that help to avoid future problems doing things right from very beginning.

API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. Each time you use an app like Facebook, send an instant message, or check the weather on your phone, you use an API.

I will try to show benefits and a few best practices for designing commonly used RESTful API – also referred to as a RESTful web service or REST API – is based on representational state transfer technology, an architectural style and approach to communications often used in web services development.

The main benefits of a well-designed API include:

• improved developer experience
• faster documentation
• and higher adoption for your API

Characteristics of a well-designed API

In general, an effective API design will have the following characteristics:

• Easy to read and work with : A well designed API will be easy to work with, and its resources and associated operations can quickly be memorized by developers who work with it constantly.
• Hard to misuse: Implementing and integrating with an API with good design will be a straightforward process and writing incorrect code will be a less likely outcome. It has informative feedback and does not enforce strict guidelines on the API’s end consumer.
• Complete and concise: a complete API will make it possible for developers to make full- fledged applications against the data you expose.

Basic principle how API works

• Client prepare a request to proper address (endpoint) and sends it
• Interface responds with a Response
• Client gets a response for the request

Collections, Resources, and their URLs

Understanding resources and collections

Resources are fundamental to the concept of REST. A resource is an object that is important enough to be referenced in itself. A resource has data, relationships to other resources, and methods that operate against it to allow for accessing and manipulating the associated information. A group of resources is called a collection. The contents of collections and resources depend on your organizational and consumer requirements.

Describe URLs with nouns

The base URL should be neat, elegant, and simple so that developers using your product can easily use them in their web applications. A long and difficult-to-read base URL is not just bad to look at, but can also be prone to mistakes when trying to recode it. Nouns should always be trusted.

Describe resource functionality with HTTP methods

All resources have a set of methods that can be operated against them to work with the data exposed by the API. RESTful APIs comprised mainly of HTTP methods which have well defined and unique actions against any resource. A list of most commonly used HTTP methods:

• GET – retrieve a resource
• POST – to create that resource
• PUT – to change the state of or update a resource
• DELETE – to remove it

Responses

Always give feedback to help developers succeed

Providing good feedback to developers on how well they are using your product goes a long way in improving adoption and retention. Good feedback involves positive validation on correct implementation, and an informative error on incorrect implementation that can help users debug and correct the way they use the product. For an API, errors are a great way to provide context to using an API. Align your errors around the standard HTTP codes.

• 400 type errors – Incorrect, client-side calls
• 500 type errors – for any server-side errors
• 200 type response for a successful method used against your resource

Give examples for all your GET responses

A well- designed API also has an example of the kind of response one can expect on successful call against a URL. This example response should be simple, plain, and quick to comprehend.

Requests

Handle complexity with care

The data you are trying to expose can be characterized by a lot of properties which could be beneficial for the end consumer working with your API. These properties describe the base resource and isolate specific assets of information that can be manipulated with the appropriate method. An API should strive towards completion, and provide all the required information, data and resources to help developers integrate with them in a seamless manner.

Get started with API design

There is no single approach to API design that will work for every project. The suggestions above are just advice and recommendations which can be used or discarded depending on your user case and requirement. One of the main reasons why API design is crucial is that it helps the end consumer use your API. Their needs should be the guiding light towards designing and building a great API.