RestFul API Concise tutorial

Hello, I’m Guide! This is my 210th great original! This article focuses on the knowledge of RestFul apis that back-end programmers must have.

RESTful apis are the basic knowledge that every programmer should know and master, and we should at least meet the most basic requirements of RESTful apis when designing apis in the development process (such as using nouns as much as possible in the interface, using POST requests to create resources, DELETE requests to DELETE resources, etc. Example: GET /notes/ ID: gets information about a note with a specified ID).

If you look at RESTful apis, they tend to be quite esoteric, and my next article will cover some conceptual things as well. However, our knowledge of RESTful apis is actually very simple and easy to summarize! For example, if I gave you the following two urls would you immediately know what they do! This is the power of RESTful apis!

The RESTful API lets you see the URL + HTTP method to know what the URL is, and lets you see the HTTP status code to know the result of the request.

GET /classes: List all classes POST /classes: Create a new classCopy the code

The following is just an introduction to some of the things I think are important about RESTful apis.

1. Important Concepts

REST stands for REpresentational State Transfer. The phrase translates as “presentation level state transition”. This may be difficult to understand, but the full name of REST is Resource Representational State Transfe, which translates bluntly as “State transfer” of “resources” in some form during network transport. If that still doesn’t make sense, keep reading and I’m sure the following will help you understand what REST is.

We’ll break down each of the concepts mentioned above to help you understand them better, but you don’t actually need to know the following concepts to understand what I’m going to cover in the next section. However, in order to better explain RESTful apis to others, I recommend that you understand them well!

• ResourcesWe can refer to real object data as resources. A resource can be either a collection or an individual. For example, our class classes represent a collection of resources, while a specific class represents a single individual resource. Each resource has a specific URI (Uniform Resource Locator) that we can access if we need to get the resource, such as a specific class:/class/12. Alternatively, a resource can contain sub-resources, such as/classes/classId/teachers: lists all teachers in a given class
• Representational: A resource is an information entity that can be presented in a variety of ways. We refer to “resources” in json, XML, image, TXT and so on as “presentation layers”.
• State Transfer: When you first see this term, you’re confused. Inner BB: What the hell is this? In plain English, state transitions in REST describe more about the state of a resource on the server side, such as when you change the state of a resource by adding, deleting, or modifying it (via HTTP verbs). Ps: Internet communication protocol HTTP is a stateless protocol. All resource states are stored on the server.

With that explained, let’s summarize what RESTful architecture is:

1. Each URI represents a resource;
2. Between the client and the server, some representation of this resource like JSON, XML, image, TXT, etc.;
3. The client uses specific HTTP verbs to perform operations on server-side resources to achieve “presentation layer state transition”.

2. REST interface specifications

1, the action,

• GET: Requests to GET a specific resource from the server. Here’s an example:GET /classes(Get all classes)
• POST: Creates a new resource on the server. Here’s an example:POST /classes(Create class)
• PUT: Updates the resource on the server (the client provides the updated entire resource). Here’s an example:PUT /classes/12(Update class 12)
• DELETE: Deletes a specific resource from the server. Here’s an example:DELETE /classes/12(delete class no. 12)
• PATCH: Updates resources on the server (the client provides the changed properties, which can be regarded as partial updates). It is rarely used, so there are no examples here.

2. Path (interface naming)

The path, also known as the endpoint, represents the specific URL of the API. Common specifications in actual development are as follows:

1. No verbs in urls, only nouns, and nouns in apis should be plural.This is because resources in REST often correspond to tables in databases, which are “collections” of the same records.If the API calls do not involve resources (such as calculations, translations, etc.), verbs can be used.Such as:GET /calculate? param1=11&param2=33
2. Instead of capital letters, use a middle bar instead of a lower bar, such as an invitation codeinvitation-codeRather than
   invitation_code

Talk is being! Let’s take a practical example to illustrate. Now that you have an API that provides information about the class, as well as information about the students and teachers in the class, its path should look like this.

Use nouns instead of verbs for interfaces. Here are some examples:

GET /classes: list all classes POST /classes: create a new class GET /classes/classId: GET /classes/classId: GET /classes/classId: Update PATCH /classes/classId: Update PATCH /classes/classId: update PATCH /classes/classId: Delete a class GET/classes/every/head: list all information the teacher GET a specified class/classes/every/students: List of a given class all the students' information DELETE classes/every/head/ID: to DELETE a specified class specified under the teacher's informationCopy the code

Example:

/getAllclasses
/createNewclass
/deleteAllActiveclasses
Copy the code

Clear the hierarchy of resources. For example, if the scope of business is schools, then schools will be the first-level resources :/schools, teachers :/schools /teachers, and students :/schools /students.

3. Information Filtering

If we need to add specific criteria in the query, we recommend using the FORM of URL parameters. Select * from class where state is active and name is guidegege:

GET /classes? state=active&name=guidegegeCopy the code

Let’s say we want to implement paging queries:

GET /classes? Page =1&size=10 // specify page 1, 10 data per pageCopy the code

4. Status Codes

Status code range:

Three bases

The ultimate RESTful is HateoAs, but this is rarely used in real projects.

These are the basics of RESTful apis, and the ones that are easiest to put into practice during normal development. In fact, RESTful apis are best for Hypermedia, providing links to other API methods in the results so that the user knows what to do next without looking up the documentation.

For example, when a user makes a request to the root directory of api.example.com, they get a document like this.

{"link": {
  "rel":   "collection https://www.example.com/classes"."href":  "https://api.example.com/classes"."title": "List of classes"."type":  "application/vnd.yourformat+json"
}}Copy the code

The above code shows that the document has a link property that the user reads to know what API to call next. Rel represents the relationship between the API and the current url (and gives the url of the collection), href represents the path to the API, title represents the title of the API, Type indicates the return type. The design of the Hypermedia API is called HATEOAS.

There is an API library in Spring called HATEOAS that makes it easier to create apis that conform to HATEOAS designs.

The article recommended

RESTful API description:

• RESTful API Tutorial
• Best Guide to RESTful apis (Yifeng Nguyen is the source of most of this article)
• Best practices for RESTful API design
• REST that we misunderstood together over the years
• Testing RESTful Services in Java: Best Practices

Using HATEOAS in Spring:

• Use HATEOAS in Spring Boot
• Building REST Services with Spring
• An Intro to Spring HATEOAS (by Baeldung)
• spring-hateoas-examples
• Spring HATEOAS Spring HATEOAS