table of Contents
RestFul API
RESTful APIIt is the basic knowledge that every programmer should understand and master. We should at least meet the most basic requirements of the RESTful API when designing the API during the development process (for example, try to use nouns in the interface, use POST requests to create resources, DELETE Request to delete resources, etc., example: GET /notes/idGet the information of a note with a specified id ).
If you read RESTful API-related articles, it is generally more difficult to understand, including some conceptual things in the following articles. However, in fact, the knowledge of the RESTful API we usually develop is very simple and easy to generalize! For example, if I give you the following two URLs, can you immediately know what they are for? This is the power of RESTful API!
With RESTful API, you can see the url + http method to know what the url is doing, and you can see the http status code to know the result of the request.
GET /classes：列出所有班级
POST /classes：新建一个班级
The following content only introduces some things that I think are more important about RESTful API, welcome to add.
1. Important concepts
REST, the abbreviation of REpresentational State Transfer . The translation of this phrase is "transformation of presentation layer state". This is very obscure to understand. In fact, the full name of REST is Resource Representational State Transfe , which bluntly translates to "resources" in a certain form of "state transfer" during network transmission . If you still can’t understand it, please read on. I believe the following explanation will definitely help you understand what REST is.
We interpret the concepts involved above to deepen our understanding, but in fact, you don’t need to understand the concepts below to understand what I will introduce in the next part. However, in order to better be able to talk about "RESTful API" with others, I suggest that you still have to understand it!
- Resource (Resource) : We can call real object data a resource. A resource can be a collection or a single individual. For example, our class classes represent a collection of resources, while a specific class represents a single individual resource. Each property has a specific URI (Uniform Resource Locator) corresponding, if we need to get the resources, this URI will be able to access, such as access to specific classes:
/class/12. In addition, resources can also contain sub-resources, such as/classes/classId/teachers: List all teachers in a specified class - Representational : "Resource" is an information entity, which can have a variety of external manifestations. We call the concrete forms of "resources" such as json, xml, image, txt, etc. as its "presentation layer/forms".
- State Transfer (State Transfer) : At first sight, everyone will be very confused? Inner BB: What is this Nima? In the vernacular, state transfer in REST describes more the state of server-side resources. For example, you can change the state of resources by adding, deleting, modifying and checking (implemented through HTTP verbs). ps: Internet communication protocol HTTP protocol is a stateless protocol, all resource states are stored on the server side.
Based on the above explanation, let's summarize what is RESTful architecture:
- Each URI represents a resource;
- Between the client and the server, transfer certain manifestations of this resource, such as json, xml, image, txt, etc.;
- The client uses specific HTTP verbs to operate on server-side resources to achieve "presentation layer state conversion".
2.REST interface specification
1) Action
- GET: request to obtain a specific resource from the server. For example:
GET /classes(Get all classes) - POST: Create a new resource on the server. For example:
POST /classes(Create a class) - PUT: Update the resource on the server (the client provides the entire resource after the update). For example:
PUT /classes/12(Update class number 12) - DELETE: Delete a specific resource from the server. For example:
DELETE /classes/12(Delete class number 12) - PATCH: Update the resources on the server (the client provides the changed attributes, which can be regarded as a partial update). It is used less, so I will not give an example here.
2) Path (interface naming)
The path is also called "endpoint", which represents the specific URL of the API. Common specifications in actual development are as follows:
- There can be no verbs in the URL, only nouns. The nouns in the API should also be plural . Because the resources in REST often correspond to the tables in the database, and the tables in the database are all "collections" of the same kind of records. **If the API call does not involve resources (such as calculations, translation, etc.), you can use verbs. **such as:
GET /calculate?param1=11¶m2=33 - No capital letters, suggested in the bar - not at the bar _ such as inviting written code
invitation-codeinsteadinvitation_code
Talk is cheap! Let's give a practical example to illustrate it! Now there is such an API that provides information about the class, as well as information about the students and teachers in the class, so its path should be designed as follows.
The interface uses nouns as much as possible and prohibits the use of verbs . Here are some examples:
GET /classes：列出所有班级
POST /classes：新建一个班级
GET /classes/classId：获取某个指定班级的信息
PUT /classes/classId：更新某个指定班级的信息（一般倾向整体更新）
PATCH /classes/classId：更新某个指定班级的信息（一般倾向部分更新）
DELETE /classes/classId：删除某个班级
GET /classes/classId/teachers：列出某个指定班级的所有老师的信息
GET /classes/classId/students：列出某个指定班级的所有学生的信息
DELETE classes/classId/teachers/ID：删除某个指定班级下的指定的老师的信息
Counterexample:
/getAllclasses
/createNewclass
/deleteAllActiveclasses
Clarify the hierarchical structure of resources. For example, the scope of the business is the school, then the school will be the first-level resource:, /schoolsteacher:, /schools/teachersand student: /schools/studentsthe second-level resource.
3) Filtering information (Filtering)
If we need to add specific conditions when querying, it is recommended to use the form of url parameter. For example, we want to query the class whose state is active and whose name is guidegege:
GET /classes?state=active&name=guidegege
For example, we want to implement paging query:
GET /classes?page=1&size=10 //指定第1页，每页10个数据
4) Status Codes
Status code range:
3.HATEOAS
The ultimate of RESTful is hateoas, but this is basically not used in actual projects.
The above is the most basic thing of RESTful API, and it is also the easiest to practice in our usual development process. In fact, RESTful API is best to be Hypermedia, that is, provide links in the returned results and connect to other API methods, so that users don't need to check the document, but also know what to do next.
For example, when a user makes a request to the root directory of api.example.com, they will get such a document.
{
"link": {
"rel": "collection https://www.example.com/classes",
"href": "https://api.example.com/classes",
"title": "List of classes",
"type": "application/vnd.yourformat+json"
}}
The above code indicates that there is a link attribute in the document, and the user will know what API to call next by reading this attribute. rel represents the relationship between this API and the current URL (collection relationship, and gives the collection URL), href represents the path of the API, title represents the title of the API, and type represents the return type. The design of Hypermedia API is called HATEOAS.
There is an API library called HATEOAS in Spring, through which we can more easily create APIs that comply with HATEOAS design.
Reference material: "Comprehensive Analysis of Java Intermediate and Advanced Core Knowledge" is limited to 100 copies. Some people have already obtained it through my previous article!
Seats are limited first come first served! ! !
Students who want to get this learning material can click here to get it for free """""""