I often see non-standard restful design in my work. Today, I will write an article summarizing all the scenarios and design methods I have encountered.

The core ideas

A Restful request for an address is a resource, and the requested method is an operation on the resource.

1. Use a center line for naming words in the URL

/children-books
/children_books
/childrenBooks
/ChildrenBooks
Copy the code

Although some restful design sites also use underscores, by comparison, the center line is the best for display and URL feel

2. Do not use the verb, by POST/GET/PATCH/PUT/DELETE representative action

A resource address is a noun path, and a method is a verb operation. Restful is designed to avoid using verbs in urls, because verbs can be written in many ways, such as modifying a book

POST /modify-book
POST /update-book
PUT /book-change
Copy the code

Such different ways of writing can easily lead to confusion, so it is better to operate the verb uniformly.

Resource action verbs (Http request methods)

GET Obtain resource information POST Add resource PUT Update the entire resource PATCH Update some resource information DELETE DELETE resourceCopy the code

The right example

Resource address https://www.example.com/books/1 GET/books to obtain a list of all the books GET/books / 1 GET id of 1 book POST/add a new book PUT books/books / 1 Update the overall information about the book whose ID is 1 PATCH /books/1 Update some information about the book whose ID is 1 DELETE /books/1 DELETE the book whose ID is 1Copy the code

3. Use plural resources

Use singular and plural names to name resources, so use plural names

GET /books GET /book/1 GET the book whose ID is 1 (error) PUT /book/1 (error)Copy the code

In the example above, the list of books is plural because it is multiple books. If the list of books is single or other requests, some singular and some plural urls are confused. Another reason to keep plural numbers is that frameworks such as backend SpringBoot often annotate URL prefixes on controllers, and being singular and plural can make code cumbersome.

4. Use resource ownership correctly

If a resource has an ownership feature, you can use the following format

/users/{id}/books/{id} user a book /books/5/comments A list of comments whose ID is 5Copy the code

When designing urls, pay attention to the order of attribution.

5. Use the HTTP status code as the request result status

200 The request succeeded. 3XX Redirection 4XX client request error. 5XX Server request processing errorCopy the code

Detailed www.runoob.com/http/http-s…

With a status code representation, 200 can return interface information directly, and only requests that are not 200 need to return ErrorCode.

6. Use Query to filter resources

/books? Type =fiction Get a book in the type of fictionCopy the code

7. Resources of the current user

Generally we need to provide a series of interfaces for the current user’s resources, which can be used to obtain personal information, modify personal information, or represent some attribute content owned by the user. The feature of these interfaces is that the user passes the token (with id information) to the back end, and the back end returns the information, so the ID number is not placed in the URL. In this case, you can change the resource name from plural to singular to represent the current user.

PUT /user Updates the personal information of the current user. GET /user Updates the personal information of the current user. PUT /userinfo Updates the personal information GET /me/todos A list of toDos for the current user (some websites also use words like me in their design)Copy the code


As mentioned earlier, the core idea of restful is to operate on resources at resource addresses, but actual business scenarios often go beyond that, and the design of these requests may not always follow the above principles. The request method is usually POST.

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

8. Resource acquisition interface expansion

Due to service requirements/Users interface needs to be designed into two extensions, one of which only returns the basic information of the user, such as name, profile picture, etc., while the other one is used in the user details page to return more user information, such as interests and hobbies, or even add some link table content.

GET /users/1
GET /users/1/detail
Copy the code

9. Expanded resource operation interfaces

Order Product information modification + Order delay Receiving For a resource, only one PUT or PATCH interface is available for modifying information, which cannot process complex service scenarios, such as an order. Multiple interfaces are required to process different user operations

PUT /orders/100 POST/Orders /100/Copy the code

Attention should be paid to the operation after the resource. There are controversies over whether to use verbs or nominalized verbs. In line with the principle that there should be no verbs in the address as resource, some people think that all verbs should be nominalized, such as “cancel to Cancellation “, while others think that verbs should only be used. After referring to the restful design of many foreign websites, I personally suggest using verbs, because not all verbs can be nominalized, and the team should discuss and unify it internally. In addition, this type of extension usually uses POST to generate a PDF of a book without adding, deleting, or searching resources

POST /books/1/ PDF -generation (noun) POST /books/1/ PDF -generate(verb)Copy the code

10. Resource search

This search function is to find all resources, and not specific to any resource, can be designed as

POST /searches? Typically, the body also has many query criteriaCopy the code

This can be interpreted as you creating a search resource using the keyword and then returning the result.


But for a specific resource lookup, the GET method is more appropriate

GET /books? keyword=xxxCopy the code

11. Perform resource operations

Bank transfer function The actual operation of the transfer of a number of data, to their own bank account deduction, add money to the new account, there are also a lot of operations, such as saving the transfer record.

POST /transfer
Copy the code

Modifying invoice is accompanied by several processes, not simply to modify the database information, the original invoice information is retained, but to make a new red invoice, and there are operations such as generating PDF and sending emails.

POST /invoices/1
Copy the code

12. Contracts are legally relevant

POST is used for any action that requires a warranty on contracts, laws and terms such as agreeing to a user agreement, confirming a lease contract, generating electronic contracts, confirming identity information.