What is Restful API
REST is a style rather than the standard. It refers to the interaction in the form of client and server. The core idea is that data manipulation instructions sent by the client are "verb + object" structure.
Restful API has several features:
Resources for: Interface name are zoos, animals, rather than getAllAnimals such
use Http verb: GET/PUT/POST/DELETE/PATCH/HEAD/OPTIONSrather than just our daily use of GET and POST
Design Principles
1, when the interface should be named with nouns, verbs should not be used, because, by the interface operation to the resource.
2. Add the version number in the url, which will help management more intuitive version iteration
https://www.rgc.com/v1/
3, for the type of operation resources should be represented by the http verb.
- GET / zoos: List all zoo
- POST / zoos: Create a new zoo
- GET / zoos / ID: obtaining information about a specified Zoo
- PUT / zoos / ID: Updates a specified Zoo (providing all the information the zoo)
- DELETE / zoos / ID: delete a zoo
- GET / zoos / ID / animals: List all the animals of a given zoo
- DELETE / zoos / ID / animals / ID: delete the specified a specified animal zoo
4, HTTP Method for each resource operations CURD
- GET (SELECT): Remove the resource from the server (one or more).
- POST (CREATE): a new resource on the server.
- PUT (UPDATE): update the resource (after the complete resources provided by the client to change) in the server.
- PATCH (UPDATE): Updating Resource (provided by the client to change the properties) in the server.
- DELETE (DELETE): Delete the resource from the server.
5, plural URL, URL since it is a noun, you should use the plural or singular?
This is no uniform requirement, but common operation is to read a collection, such as GET / articles (read all the articles), there should obviously be plural.
For the sake of consistency, the proposed use complex URL, such as GET / articles / 2 better than GET / article / 2.
6, avoid multi-level URL
Common situation is that resources need to multi-level classification, so it is easy to write multi-level URL, such as access to an author of some articles.
GET /authors/12/categories/2
This URL is not conducive to expansion, semantics is not clear, often in order for a while, in order to understand the meaning.
Better yet, in addition to the first level, the other levels are used query string expression.
GET /authors/12?categories=2
Here is another example, query the published article. You may be designed to the following URL.
GET /articles/published
The query string wording significantly better.
GET /articles?published=true
issues
1, if there is a record in a variety of actions how to do it?
There are two ways:
- The first
POST /datas/1?action=reportError
POST /datas/1?action=mark
POST /datas/1?action=assign- The second
POST /datas/1/reportError
POST /datas/1/mark
POST /datas/1/assignObviously the above two methods would be better the second
2, client authentication user name or phone if there is, how to design?
It may be designed such that
GET /users/{userName}?action=check, for operation of check userName
Reference Reading
http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html