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

This article mainly introduces "what is the correct way to write the API interface design under the Restful architecture style". In the daily operation, I believe that many people have doubts about the correct writing method of the API interface design under the Restful architecture style. The editor consulted all kinds of materials and sorted out a simple and easy-to-use operation method. I hope it will be helpful to answer the doubt that "under the Restful architecture style, what is the correct writing method for the API interface design?" Next, please follow the editor to study!

1. Query an object API: GET / app/getImportantApp@GetMapping (path = "/ getImportantApp") public R getImportionApp (@ RequestHeader ("pid") String pid2, query list API: GET / app/list@RequestMapping ("/ list") public R list (String deptId) 3, save object API: POST / app/save@PostMapping ("/ save") public R add (CmsAppLicationEntity appLication) String deptId) 4. Delete object interface: POST / app/delete@DeleteMapping ("/ delete/ {applicationId}") public R delete (@ PathVariable ("applicationId") long applicationId) 5. Update object interface: POST / app/batchUpdate@PostMapping ("/ batchUpdate") public R batchUpdate (@ RequestBody List list)

Is it the code that feels familiar? is it written correctly? It looks intuitive and easy to understand. If you use the Restful architecture style, the above five writing methods are certainly wrong, which is due to the lack of understanding of the Restful architecture style.

Wechat search official account "ape core", backstage private message reply 1024 free to get a full set of video materials such as SpringCloud, SpringBoot, WeChat Mini Programs, Java interview, data structure, algorithm, etc.

Restful architecture style definition

"Restful is a software architecture style, design style, not a standard, but provides a set of design principles and constraints. It is mainly used for client-server interaction software. Software designed based on this style can be more concise, more hierarchical, easier to implement caching and other mechanisms.

Due to the lack of a thorough understanding of the Restful architecture style, there are generally three controversial design misunderstandings.

Misunderstanding 1 request path URI is a verb, not a noun problem

Misunderstanding 2. The problem of version number in URI

Misunderstanding 3. The case of paths in URI

Misunderstanding 1 request path URI is a verb, not a noun problem

According to the Restful architecture style, each business entity represents a resource and a noun.

For example, when designing a product list interface:

Erroneous writing

/ getProductList

The verb get appears in the request path / getProductList path, which is incorrect.

Recommended writing method

/ products

In addition, it is also incorrect for URL to appear / addProduct, / deleteProduct, / updateProduct and so on.

If there is an action that cannot be expressed by a HTTP verb, you should turn it into a resource.

For example, if we get the list of products under the user, the wrong interface design is:

POST / users/1/getProducts

Or

POST / users/1/getProductList

The correct way to write is to change the verb getProducts into the noun products

POST / users/1/products misunderstanding II problem with version number in URI

There are three opinions in the industry as to whether there is a version number in the URI.

The first is to add the version number to the request path, for example:

POST / products/v1 GET / users/v1 POST / orders/v1 POST / items/v1

According to this argument, adding a version to URI avoids backward compatibility, and it can also reduce the cost of migrating users to a new interface through expiration prompts, redirects, documentation, and other means.

Of course, some people are in favor of adding the version number to the request path, while others oppose the addition of the version number. They think that:

Adding the version number will confuse the service interface. It is often encountered that some low-version API interfaces call some high-version API interfaces, resulting in data parsing errors, which undoubtedly increases the cost of user migration.

Version has nothing to do with the concept of resources, so adding a version to URI can confuse users.

Another argument is that adding a version number to the path is a wrong way to design. In the Versioning REST Services article written by foreigners, you should specify your version number in the Accept of the request header, not in the request path.

For example:

For example, for versions 1.0, 1.1, and 2.0 of the foo data type as JSON set the Accept/Content-Type header as follows: 1.0: vnd.example-com.foo+json; version=1.0 1.1: vnd.example-com.foo+json; version=1.1 2.0: vnd.example-com.foo+json; version=2.0

The front-end js specifies the version version=1.1 of the vnd.example-com.foo+json; version=1.1 in the request header Accept.

$.ajax ({beforeSend: function (req) {req.setRequestHeader ("Accept", "vnd.example-com.foo+json; version=1.1");}, type: "GET", url: "http://http://www.example.com/foo/12", success: function (data) {/ * code elided * /}, dataType:" json "})

Personally, I prefer to add the version number to the request path, because I think the additional version number is to consider the interface migration of the new and old versions from a program point of view, especially when the micro-service architecture is popular and the business granularity is very fine. should the original version be retained for the upgrade of the interface?

When should I add the version number?

"if the restful interface you develop is open and you don't know who has called it, then the version number is necessary. Take Baidu Map Interface as an example. Baidu has released a restful-style map interface on the Internet, which can be called by various industries throughout the country and even around the world. Baidu wants to upgrade the interface, what should I do? If Baidu upgrades directly on the original url, what will be the result? Unpredictable. Programmer: boss, our product crashed! Boss: why? Programmer: Baidu upgraded the interface! Even if only one more field is returned, it may lead to problems with the caller's original code. after all, Baidu does not know how everyone parses the return value. The best thing to do at this time is to add the version number, keep the original version, and release the new version, and all the problems will be easily solved. Old users do not have to update the code because of Baidu's upgrade, and new users can enjoy the latest interface, perfect.

The way to determine whether to add a version number:

Do you know exactly who called your interface, and can notify you that if you can, you don't have to add the version number?

Whether the original version is retained when the restful interface is upgraded. If not, the version number may not be added.

Of course, there are some tricks to add the version number, the version number should be placed after a functional module, or even a url should have its own independent version, such as api/user/v2, so that the caller will not have the illusion that the entire interface is upgraded to v2.

Misunderstanding 3. The case of paths in URI

The path in URL should be lowercase instead of hump, for example, the following interface is miswritten.

POST / orderItems/v1/1001

Recommended writing method

POST / orders/v1/items/1001

Or

/ order-items/v1/1001 summary

I have seen a lot of micro-service code written based on micro-service architecture, and most of the interfaces look like restful style, but after careful identification, it turns out that it is a bunch of pseudo-restful interfaces, either with no distinction between verbs and nouns or confusing path versions.

In fact, the scene is that the restful style basically stays in the word of mouth, and things that look high can only be supplied high. Most programmers have been typing crazily in order to catch up with the schedule and complete the KPI.

Appendix 1 basic rules of API design style 1. Use nouns instead of verbs

Do not use:

/ getAllUsers / createNewUser / deleteAllUser2, Get methods and query parameters should not involve state changes

Use the PUT, POST, and DELETE methods instead of the GET method to change the state, and do not use GET to change the state:

3. Use plural nouns

Don't confuse singular and plural nouns. To keep it simple, use the plural only for all resources.

Deploy / cars instead of / car / users instead of / user / products instead of / product / settings, use sub-resources to express relationships if one resource is related to another resource, use sub-resources: GET / cars/711/drivers/ returns all drivers of car 711 GET / cars/711/drivers/4 returns driver 4 of car 711, declare serialization format using Http header

On both the client and the server, both parties need to know the format of the communication, which is specified in HTTP-Header

Content-Type defines the request format

Accept defines a series of acceptable response formats

6. Provide functions such as filtering, sorting, selection and paging for the collection

Filtering filtering: filter with unique query parameters:

GET / cars?color=red returns red cars GET / cars?seats

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.