The company suddenly required to use RESTful style interface address of the interface naming conventions, so restful weekend on the interface naming convention made a summary
REST is an abbreviation of a term, REpresentational State Transfer, Chinese literal translation "Characterization of a state transition."
REST is a style convention, RESTful its adjective form. For example implements a REST-style interface can be called RESTful interface.
REST data interaction is described in the rule layer HTTP client and server; client by sending HTTP (s) request, the server receives the response, complete a HTTP interaction to the server. This interactive process, REST framework agreement adopted two important aspects of the method is an HTTP request, as well as links to the request.
Thus, REST brute specification may be abstracted into two rules:
- API request to locate the resource indicated by the URL;
- METHOD request indicates that the operation of the resource;
The following will both rule-based, describing how to construct a REST request meets specifications.
API's url
URL used to locate resources, with separate operating area to be carried out, which means that URL should not have any verb.
1.1 The following examples get, create, search verbs, should not appear at the rear end of the REST architecture interface path. such as:
/api/getUser/api/createApp/api/searchResult/api/deleteAllUsers
1.2 when we need to operate for a single user, depending on how these operations may require different following interfaces:
/api/getUser （用来获取某个用户的信息，还需要以参数方式传入用户 id 信息）/api/updateUser （用来更新用户信息）/api/deleteUser （用来删除单个用户）/api/resetUser （重置用户的信息）
1.3 may be different when updating user information, provide different interfaces, such as:
/api/updateUserName/api/updateUserEmail/api/updateUser
1.4 Summary:
The drawbacks of the above three cases: first add the verb, the URL must be longer; secondly to a different operating entity of resources is a different URL, causing excessive URL difficult to manage.
In fact, when you go back and look at the definition of "URL" of the term, to better understand this. URL means Uniform Resource Locator, the term has been clearly shown that a URL should be used to locate resources, and should not be incorporated into the description of the operational behavior.
Link REST architecture should look something like this:
A request API is used to locate the resource indicated by the URL
1, URL should not appear in any of the verb representations of operations, only for a corresponding link resource;
2, URL should distinguish between singular and plural, the recommended practice is always in the plural; for example, retrieves a list of users; If you get a single resource, the incoming ID, for example, represents an individual user access to information; (personally think that we should distinguish between single plural, / API / the users retrieves a list of users; represents an individual user access to information written by the benefits of such an address that will be able to return an entity is an object, or a collection).GET /api/users/api/users/123/api/user/123
3, according to the logic level of resources, a URL nesting, such as a user belongs to a team, and this team is one of many teams; then get the user interface might look like this: GET / api / teams / 123 / members / 234 retrieves the id of the group 123, id 234 as member information.
In a similar rule can be written as follows interface
/ api / teams (corresponding to TeamList)
/ API / Teams / 123 (corresponding to the group ID 123)
/ API / Teams / 123 / Members (ID 123 corresponding to the team member list)
/ API / teams / 123 / members / 456 (corresponding to the ID is not a member ID 456 in the group 123)
II METHOD requested resource indicates the operation of this
GET (SELECT): to retrieve a specific resource from the server, or a list of resources.
POST (CREATE): create a new resource on the server.
PUT (UPDATE): updated resources on the server, providing the entire resource.
PATCH (UPDATE): updated resources on the server, only the changed properties.
DELETE (DELETE): Delete the resource from the server.
Right:
Single resource (Singular-resourceX)
url sample: order / (order refers to the individual resources the X-)
GET - returns a new the Order
POST-create a new order, request carrying content from post acquisition value.
With a single resource id (Singular-resourceX / {id})
the URL Sample: order / 1 (order refers to the individual resource X-)
the GET - returns the id of the order 1 is
DELETE - delete the order 1 is the id
PUT - Update id 1 is an order, the order value of the content acquired from the request body.
Complex resource (plural-resourceX /)
the URL of the sample: orders /
GET - returns all orders
Complex resource discovery (plural-resourceX / Search)
? The URL of the sample: the Orders / Search name = 123
GET - order the return of all the resources that satisfy the query. (Query By Example, unrelated) - order the name is equal to 123.
Complex resource discovery (plural-resourceX / searchByXXX)
the URL of the sample:? Orders / ipad searchByItems name =
GET - returns all orders meet custom queries - Get the names of all the items are orders associated ipad.
The singular resource (Singular-resourceX / {ID} / pluralY)
the URL Sample: order / 1 / items / (where is the order resource X, items plural resources is the Y)
the GET - returns all order id is associated items 1 .
resourceX-Singular / {ID} / Singular-resourceY /
the URL Sample: Order / 1 / item /
the GET - returns a new transient item and order id Example 1 is associated.
POST - Create an instance of the order id is the item 1 is associated. Item values acquired from the post request body.
resourceX-Singular / {ID} / Singular-resourceY / {ID} / Singular-resourceZ /
the URL Sample: Order /. 1 / Item / 2 / package /
the GET - returns a new instance of a package with a transient item2 and the associated order1 .
POST - Creates a new instance of the item order1 package 2 and the associated value of the package body obtained from the post request.
Above specification is based on a query-based, focused on the following to say about the patch
patch primarily used to change part of the field, such as renaming, or change the status of the entities. This time should write ,, two methods are not written Patch / order / {id}, such a distinction is not come out. This time you can do so
/ Order / {id} / name (to rename)
/ Order / {id} / status (used to change the state of the user)
So that you can separate the two methods are two ways to perfect the url and method of the area.
Here special note, the blog using some / order / name / {id} This naming convention, the id on the back of the field, I'm not sure that is correct, but according to the relevant rules of queries, I still choose id directly with the right people behind the order.
The above rules may continue recursion, and resources behind the complex will never follow a negative resource.
Summarize a few key points to clearer presentation rules.
When using plural resources, the return is the last example of complex use of resources.
When using a single resource, but the return is the last example of the use of resources.
When queried, it returns an instance of (their) last complex entity.
Other specifications
Other specifications:
Rule. 1: the end of the URI should not contain (/)
Rule 2: Separator forward slash (/) must be used to indicate a hierarchical relationship
Rule 3: Use a hyphen (-) to increase the readability of the URI
rule 4: Do not use an underscore in the URI (_)
rule 5: URI path in all lowercase letters
Reference blog
https://blog.csdn.net/qq_35075909/article/details/91522242
https://www.cnblogs.com/alsf/p/9362264.html