🤖 英 æ–‡ link: medium.com/hackernoon/…

Facebook, Google, GitHub, Netflix and other tech giants have become platforms for developers and products to interface with their data.

Even if you don’t provide aN API for other developers or products, it’s always important for your application to have a well-designed API.

There is a lot of discussion on the Internet about API design best practices, and there are no official guidelines for this.

An API is an interface through which many developers interact with data. A well-designed API is always easy to use and makes a developer’s life very smooth. The API is the developer’s GUI, and if it’s confusing, the developer will start looking for an alternative or stop using it. The developer experience is the most important measure of API quality.

A glossary

Here are the most important terms associated with the REST API.

  • A resource is a representation of an object or something that has some associated data and can have a set of methods to operate on it. For example, animals, schools, and employees are resources that are deleted, added, updated, and so on.
  • A collection is a collection of resources, such as Companies is a collection of Company resources.
  • A URL (Uniform Resource Locator) is a path through which a resource can be located and some action can be performed on it.

2. API path

To make it easier to understand, we can write some apis for companies that have employees.

/getAllEmployees is an API to get a list of employees. More information about a company’s API is shown below:

  • /addNewEmployee
  • /updateEmployee
  • /deleteEmployee
  • /deleteAllEmployees
  • /promoteEmployee
  • /promoteAllEmployees

There are many similar API paths for different operations. All of these will involve a lot of repetitive actions. Therefore, as the number of apis increases, maintenance of all these API paths becomes onerous.

What went wrong

Urls should contain only resources (nouns) and not actions (verbs). The API path /addNewEmployee contains the action addNew and the resource name Employee.

What’s the right thing to do

A good example is /companies, which does not include actions. The question then becomes, how do we tell the server what to do on the “company” resource: do we add, delete, or update?

This is where the HTTP methods (GET, POST, DELETE, PUT) (also known as verbs) come into play.

In the API path, the resource is always a collection, and if we want to access an instance of the resource, we can always pass the ID in the URL.

  • GETMethod request/companiesShould be able to get all the companies;
  • GETMethod request/companies/34Should be able to getidCompany details of 34;
  • DELETEMethod request/companies/34It should be deletedid34 companies;

In some other use cases, if we had a resource (such as an employee in a company) under a resource collection, then some simple API paths would look like this:

  • GET /companies/3/employeesShould getidFor all employees of 3;
  • GET /companies/3/employees/45Should getidFor companies of 3idStaff details of 45;
  • POST /companiesA new company should or should be created, and details of the new company just created will be returned;

Is the API now more accurate and consistent 😎

Summary: The path should contain the complex form of the resource, and the HTTP method should define the type of operation to perform on the resource.

3. HTTP method (verb)

HTTP defines a set of methods that indicate the type of action to be performed on the resource.

A URL is a sentence in which the resource is a noun and the HTTP method is a verb.

Here are some of the more important HTTP methods:

  1. GETMethod to retrieve data from a resource and should not cause side effects. Such as:/companies/3/employeesReturns theidAll the employees in the company of 3.
  2. POSTMethod asks the server to create a resource in the database, usually by submitting a form. Such as:/companies/3/employees/johnforidCreate a new employee for company 3. POST is non-idempotent, meaning that multiple requests will have different effects.
  3. PUTMethod either requests to update a resource or creates a resource if one does not exist. Such as:/companies/3/employees/johnThe server is required to update, or the resource is created if it does not existidIs the John resource in the company employee set of 3. PUT is idempotent, meaning that multiple requests will have the same effect.
  4. DELETEMethod requests that the resource or instance be deleted from the database. Such as:/companies/3/employees/john/The server will be asked to deleteidIs the John resource in the company employee set of 3.

We will discuss some of the other approaches in another article.

4. HTTP status code

When a client makes a request to the server through the API, the client should know the feedback, whether it failed, passed the request, or made an error. HTTP status codes are a standardized set of codes that can be interpreted differently in different scenarios. The server should always return the correct status code.

Here are some important categories of HTTP status codes:

2XX (success)

These status codes indicate that the server received and successfully processed the requested action.

  • 200 Ok indicates the standard HTTP response that a GET, POST, or PUT has successfully executed.
  • 201 Created This status code should be returned whenever a new instance is Created. For example, creating a new instance using the POST method should always return the 201 status code;
  • 204 No ContentIndicates that the request was successfully processed, but nothing was returned. DELETE is a good example.DELETE /companies/43/employees/2The API will be removedidOf 43 companiesidFor employee information of 2, we do not need to return any data in the API’s Response because we explicitly ask the system to delete it. If it appears like the database does not existidFor an employee of 2, then the response code will not be 2xx but 4xx.

3xx (Redirection)

  • **304 Not Modified ** Indicates that a response already exists in the client’s cache. Therefore, there is no need to transfer the same data again.

4xx (client error)

  • 400 Bad Request Indicates that the client Request is not processed because the server cannot understand the client Request.
  • 401 Unauthorized Indicates that the client is not allowed to access the resource. An Unauthorized request should be made again with the required credentials.
  • 403 Forbidden Indicates that the request is valid and the client has been authenticated, but the client is not allowed to access the page or resource for any reason. For example, sometimes authorized clients are not allowed to access directories on the server.
  • 404 Not Found Indicates that the requested resource is Not available.
  • Gone indicates that the requested resource that has been intentionally moved is no longer available.

5xx (server error)

  • 500 Internal Server Error indicates that the request is valid, but the Server is completely confused and the requesting Server is serving some unexpected condition.
  • 503 Service Unavailable Indicates that the server is down or unable to receive or process requests. In most cases, the server is under maintenance.

5. Field name conventions

You can follow any field name convention, but be sure to keep it consistent throughout your application. If the request body or response type is JSON, use camelCase for consistency.

Vi. API version

Updating your API with disruptive changes when it is used around the world can also break existing products or services that use your API.

http://api.yourservice.com/v1/companies/34/employees is a good example, he has a version information in the API path. If there are any significant updates, we can name the new set of apis v2 or V1.x.x.