(Turn) Designing the RESTFul API in this way may make you more efficient

Under the current background that the mobile terminal and the front end tend to be unified, the API based on RESTFul is also shining brightly. We need to deal with the API more and more, and the design of scalable and easy-to-maintain API is also in our work. become more important. So, is it possible, through certain testing strategies and guidance methods, to make the API design more standardized, more rules-based, and efficiently design a useful API? This article attempts to summarize the author's thinking in this regard, hoping to inspire readers.

Before we start, let's define what kind of API can be regarded as an excellent API. The following are the four elements that the author believes that an excellent API needs to meet:

1. Follow the best practices in the industry
2. High degree of uniformity and Consistency, an excellent API must be highly consistent and unified, and follow certain commonalities and conventions .
3. Reasonable abstraction based on a deep understanding of the business. For the guidance method of API design, the author's understanding of these four elements is introduced in detail below, and cases are provided to illustrate when necessary. Follow the industry's best practices Follow the industry's best practices. I think it is the most basic element that an excellent API should have. It allows relevant personnel to understand the fastest and establish a unified basic cognition. If our API is external, it will appear more important. For the purposes of this article, I'm referring to industry best practices for HTTP-based RESTful APIs. It uses URI to represent resources and HTTP Verb to represent operations. To design a RESTFul API, it is necessary to deal with the abstraction of resources to a great extent. As for what the RESTFul API is more specifically, and what principles are there, this article will not discuss more, and there are many related materials on the Internet. High level of uniformity and consistency














If following the best practices in the industry is the foundation, then maintaining the uniformity and consistency of the API is the guarantee of designing a qualified API. If our API is not unified, inconsistent, and lacks necessary conventions, users will inevitably be confused, and the cost of learning and maintenance will be greatly increased.

The following is a list that needs to be considered to ensure a high degree of API uniformity and consistency, which may not be complete:

1. Unification of authorization and authentication methods
2. Unification of paging methods for each API and corresponding parameters
3. Unification of sorting parameters and corresponding behaviors Consistent
4. The query conditions are written in advance and are consistent
5. Consider the global parameters to form basic cognition
6. Etc. etc.

Deeply understand the high abstraction

of the business It should be basically qualified and can meet the needs of daily business, but for excellent APIs, this is just the beginning.

When designing APIs, many people don't have a big picture and only design for the interface. Only when the front-end interface changes, the API may need to be redesigned, resulting in poor scalability and frequent modification of the API.

Therefore, when we design APIs, we need to stand at a higher dimension and abstract higher-level APIs on the premise of in-depth understanding of the business. Such APIs are generally interface-independent. Even if the interface changes, as long as it is not a business adjustment, the impact will not be great.

A good API is like a good product, not in how many APIs (functions) are provided, but in how many problems it solves. A good API can directly solve many problems that can only be solved by a general API.

Let's take an example:

If we have such a requirement, in a blog system, we need to get the most visited and least visited articles on the whole site, each n articles, how should we design the API?
There are two versions:

Version 1:

Provides two APIs, as follows:

GET /posts/most-viewed?limit=10 - Get the most visited articles
GET /posts/least-viewed?limit=10 - Get the least visited articles
Version 2:
Provide an API, use the sort parameter to sort, and indirectly achieve the requirements

GET /posts?sort=total_views desc&limit=10 - Get the most visited articles
GET /posts?sort=total_views asc&limit=10 - Get the least visited articles In the
author opinion, Version 2 will be better, directly using the existing API and sorting to complete the requirements, and the scalability and abstraction level are higher.
Explore business commonalities and summarize specifications

Each business may have its commonalities. If these commonalities are extracted and formed into specifications, it will greatly improve the efficiency of API design and development, and the use of APIs will also benefit from it, because the overall API understanding will be much easier.

For example, the company where the author is currently working faces many toB businesses and has many aggregated statistical requirements. If each statistical requirement is written as a separate API, the number of APIs may be huge and difficult to maintain.

Therefore, we are thinking about how to abstract these common statistical requirements, summarize them into specifications, and become part of the API design specifications to guide API design.

For example, we have the following business requirements:

the user's status (status) is active, disabled and achieved, and we need to count the number of each of the three states of the user that meets the conditions.
Under our current API design specification, instead of providing a new API, we will solve this requirement in the following way:

GET /users?kw=foo&$aggregate=status Press status to aggregate statistics, and kw is a query parameter
Here we introduce The aggregation method of $aggregate solves this requirement without adding a new API, and this method also becomes the specification for solving this type of problem.

The four elements of designing a good API have been introduced. I hope it will be helpful to you. I will share the design ideas of the API specification in the future~

February 18, 2017