Shulou(Shulou.com)06/03 Report--

How to design a Web API that conforms to the specification? In fact, it is not difficult to solve this problem, so the editor summarizes this article. Let's take a look at the design scheme of Web API that conforms to the specification.

1. Overview

WEB API has a wide range of application scenarios, such as opening existing system functions or data to partners or biosphere, publishing widgets that can be embedded into other web pages, building WEB applications separated from front and rear, developing mobile applications across different terminals, integrating different systems within the company, and so on.

two。 Evaluation criteria

We can judge a WEB API from three dimensions:

Easy to use: are WEB API users programs or people? I think it is the people first, then the program. Why would you say that? The decision whether to adopt a certain WEB API is made by people, and a good WEB API must conform to people's aesthetic, such as: short and easy to remember, easy to understand, easy to enter and so on. From a program point of view, WEB API should follow industry standards and do not need to do special processing when calling, which is conducive to the reuse of existing code or tools. Easy to change: after a WEB API is released and launched, it is inevitable to make updates and modifications according to the feedback of real users or the needs of business development. These updates and modifications must not affect users as far as possible. Either provide multi-version support, or provide users with practical update strategies, and so on. Robust and stable: public WEB API may be exposed to * *, and the number of visits cannot be accurately estimated. A good WEB API must have security mechanisms such as anti-injection, anti-tampering and anti-replay, and avoid service breakdown when traffic increases sharply.

Only by achieving the above three aspects can we have the strength to open an WEB API to the public and be tested by the public. Good WEB API is not only easy to use, but also helps to enhance the technical influence of individuals or enterprises, thus forming a positive cycle and bringing more and more business value. In order to design a beautiful WEB API, we need to understand the relevant design specifications and factual standards, and try to follow them in the design and development process.

3. Design specification 3.1URI is easy to input URI, short and non-redundant. Each WEB API is a service. "service" in the following counterexample is redundant, and "api" is repeated twice. This redundancy is not conducive to memory and input: counterexample: http://api.example.com/service/api/users positive example: http://api.example.com/users easy to read URI, do not use abbreviations at will, abbreviations must conform to international standards and specifications, do not invent out of thin air. For example: country Code definition (ISO3166). In the counterexample, there are two abbreviations "sv" and "u". Without additional instructions, the user has no idea what it means: counterexample: http://api.example.com/sv/u does not have a mixed case URI. The HTTP protocol (RFC7230) stipulates that except for the schema and hostname, all other information in URI should be case-sensitive. The following two counterexamples are mixed case, which is not convenient for memory. Counterexample: http://api.example.com/Users/12345 counterexample: http://example.com/API/getUserName is easy to modify URI, and there is a predictable rule in naming. The following example makes it easy to guess that changing the final ID will allow you to access information about other products. Positive example: http://api.example.com/v1/items/123456 will not expose the URI,URI of the server architecture. It only needs to reflect the function, data structure and meaning, and does not need to expose the information about how the server operates. This information is meaningless to users, and there are potential risks. Malicious users may use this information to find loopholes and initiate services. Counterexample: http://api.example.com/cgi-bin/get_user.php?user=100 rules uniform URI, ensuring the use of unified rules and style, convenient for users to remember and use. In the following counterexample, the first URI takes query parameters and the second URI takes path parameters, which are not consistent and can easily lead to confusion. Counterexample: get friend information, http://api.example.com/friends?id=100 counterexample: send a message, http://api.example.com/friend/100/messages positive example: get friend information, http://api.example.com/friends/100 positive example: send a message, http://api.example.com/friends/100/messagesURI is best composed of nouns. The full name of URI is uniform Resource Locator (Uniform Resource Identifier), which is used to identify the location of resources on the Internet, similar to a mailing address, which is made up of nouns. There are also some matters needing attention in the use of nouns: first, use the plural form of nouns; second, try to use most of the words used in API to express the same meaning; third, express it through as few words as possible; fourth, try not to use strange acronyms. Do not use spaces and characters that need to be encoded, such as using Chinese in URI. Using the connector (-) to connect multiple words, the spine method is recommended: first, the hostname (domain name) in URI allows the use of hyphens but forbids the use of underscores, and is not case-sensitive. Second, the dot character has a special meaning in order to be consistent with the rules of the host name. Spine method: http://api.example.com/v1/users/12345/profile-image Snake method: http://api.example.com/v1/users/12345/profile_image Hump method: http://api.example.com/v1/users/12345/profileImage3.2 query parameters in many scenarios we need to use API to obtain data in batches. We often struggle with what kind of query parameters to use. There are two commonly used parameter designs in the industry (per-page and page, limit and offset) to identify the amount of data obtained each time and the starting location. In the process of obtaining data in batches, the records in the data set may be added or deleted, so we need to pay attention to the different effects of using relative position or absolute position. Style 1: http://api.example.com/friends?per-page=50&page=3 style 2: http://api.example.com/friends?limit=50&offset=100 in the design of filtering parameters, the industry also has some factual standards for reference. If we expect the value of a specific attribute of the query result to be exactly the same as the value of the filter parameter, the name of the filter parameter is usually the attribute name; if we expect any attribute part of the query result to contain the value of the filter parameter, the name of the filter parameter is usually "Q". Exactly: http://api.example.com/v1/users?name=ken full-text search: can http://api.example.com/v1/users?q=kenURI contain the verb "search"? API, an online service that usually focuses on search, can be included, except that it is recommended to use nouns in the plural. The common English words "search" and "find" have the meaning of search, but there are still some slight differences between them, in which "search" is used for fuzzy search and "find" is used for precise query. Fuzzy search: is an attribute of http://yboss.yahooapis.com/ysearch/web?q=ipod used as an element of the URI path or as a query parameter? We can judge according to the following rules: if the attribute information can uniquely locate the resource, then it is suitable as a path component element, otherwise it is used as a query parameter; if the attribute can be omitted, then it is suitable as a query parameter. Path element: http://api.example.com/v1/users/{id} query parameter: http://api.example.com/v1/users?name=ken3.3 HTTP method

According to the original intention of the HTTP protocol, URI is used to identify the target object (resource), while the HTTP method is to represent the operation method. SOAP, a simple object access protocol based on HTTP protocol, is gradually replaced by RESTful's native HTTP protocol. There is no need for us to add icing on the cake. It is best to understand the HTTP protocol and make full use of its features.

GET / v1/users/123 HTTP/1.1Host: api.example.comGET, get resource POST, add resource PUT, update existing resource DELETE, delete resource PATCH, update part of resource HEAD, get meta-information of resource

If you encounter a scenario that cannot be covered by the above HTTP method, it is usually because the design granularity of the resource is too large, and we can decompose the coarse-grained resource into multiple fine-grained resources. In terms of the professional ability to design WEB API using HTTP protocol, the industry divides it into four levels. LEVEL3 is relatively idealized and lacks the basis for implementation. LEVEL2 is feasible:

LEVEL 0: use HTTPLEVEL 1: introduce the concept of resources LEVEL 2: introduce HTTP verbs (GET/POST/PUT/DELETE, etc.) LEVEL 3: introduce the concept of HATEOAS 3.4 response data

The commonly used data formats are: HTML, XML, JSON, YAML, etc. If our service supports different types of data formats in response, how can the application get the response data in the desired format when calling the service? In general, we can consider the following ways to specify data formats:

How to use query parameters: example: https://api.example.com/v1/users?format=xml uses an extension: example: https://api.example.com/v1/users.json uses the method of specifying the media type at the beginning of the request. This method is preferred: GET / v1/usersHost: api.example.comAccept: application/json.

What information should the response data contain? Is it better to have more? Or the less, the better, including only ID? The recommendation is to return on demand and return the corresponding data according to the needs of the business function. If a WEB API needs to be provided for different business scenarios, and different business scenarios have different requirements for data attribute information, we can allow users to select the content of the response. The selection method is to specify through the query parameters:

Example: http://api.example.com/v1/users/123?fields=name,age

The structure of response data should be as flat as possible, do not nest too deeply, and reduce the load of information without specific meaning, so that the size of the message can be compressed and the bandwidth can be saved. Of course, if the hierarchy is more advantageous, it can also be used.

3.5 error message

It is suggested that the error message is expressed by the status code of the header of the HTTP protocol, rather than encapsulated in another layer. The advantage of complying with the protocol specification is that it can reduce the cost of communication, and many mature software and hardware products can also be used to deal with abnormal error messages. The HTTP protocol specifies five types of status codes:

1XX: message 2XX: successful 3XX: redirect 4XX: errors caused by client 5XX: errors caused by server side

We need a usage scenario for each status code to ensure that the status code is used correctly. In addition, the service also needs to return detailed error information to the client, and we can usually use the following two ways to pass the detailed error message:

Method 1: define a private header and fill it in the header of the response message. Method 2: put the detailed error information into the message body. 3.6 version management

With the development of business, every WEB API released and launched may be updated and modified, so it is necessary to introduce version management mechanism. There are three common ways to label WEB API versions in the industry:

Embed version number in URI: example: http://api.linkedin.com/v1/people adds version information to the query string: example: http://api.example.com/users/123?v=2 specifies version information by media type Accept: application/vnd.github.v3+jsonContent-Type: application/vnd.github.v3+json

Similarly, there is an industry specification for version numbering: semantic version control (Semantic Versioning) specification, website address: http://semver.org. The version number consists of three numbers connected by the dot, for example: 1.2.3, which represents the major version number, the minor version number, and the patch version number, respectively. The increase of the version number follows the following rules:

When making incompatible changes to the software, increase the major version number; when making downward compatible changes to the software or abolishing certain features, increase the minor version number; if the API of the software has not changed, but only fixed part of the bug, increase the patch version number.

According to the rules for the growth of the version number, the version number of the WEB API only needs to be marked with the major version number, because the minor version number and the patch version number can be added to be backward compatible and will not affect the user's use. only the major version number increases to require the user to update and upgrade. In addition to marking version information, we also need to design a strategy for version changes when releasing WEB API, such as how long the transition period of the old version is available, how many versions are compatible at the same time, the end date of a specific version, and so on.

This is the end of the design of Web API. I hope the above content can be helpful to you and learn more knowledge. If you think the article is good, you can share it for more people to see.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.