Restful API interface design standards and specifications

RESTful Concept

Understand and evaluate the architecture design of web-based applications , Get a powerful 、 Good performance 、 Architecture suitable for communication .REST A set of architectural constraints and principles ." If an architecture conforms to REST The constraints and principles of , We call it RESTful framework .

REST It doesn't create new technology in itself 、 Components or services , And hidden in RESTful The idea behind it is to use Web The existing characteristics and capabilities of , Better use of existing Web Some criteria and constraints in the standard . although REST Self acceptance Web Technology has a profound impact , But in theory REST The architectural style is not tied to HTTP On , Just for now HTTP Is the only one with REST Relevant examples . So what we're describing here REST through HTTP Realized REST.

RestfulAPI Guide map

understand RESTful

To understand RESTful framework , You need to understand Representational State Transfer What exactly does this phrase mean , There is something about every word in it . We talk about resources , From the definition of resources 、 obtain 、 describe 、 relation 、 State change and so on , List and explain some key concepts .

• Resources and URI
• Unified resource interface
• Expression of resources
• Links to resources
• The transfer of state

Resources and URI

URI According to resources , Resources generally correspond to entity classes in the server-side domain model

• URI It's an address, it's a resource
• URI With the version number inside 、 Suffixes are used to distinguish the presentation format
• A must have agreement
  • Using nouns 、 No verbs
  • The hierarchy is clear 、 use / To express
  • use ? Used to filter resources

Unified resource interface

standard HTTP Method contains ：GET、POST、PUT、DELETE、Patch, Their functions are shown in the following list

Get The principle of method execution process is as follows

Put The method execution flow chart is shown below

Security and idempotency

• 1、 Security ： It doesn't change the state of the resource , Read only ;
• 2、 Idempotency ： perform 1 Time and execution N Time , The effect on resource state change is equivalent .

Interface	Security	Idempotency
GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

Neither security nor idempotency guarantees that repeated requests will get the same response. With DELETE For example , for the first time DELETE return 200 Indicates that the deletion was successful , The second time back 404 Prompt resource does not exist , This is allowed .

Expression of resources

What is resource ？ What is expression ？

In essence , Anything important enough to be quoted can be a resource . If your users “ Want to create a hypertext link to it , Point out or object to claims about it , Get or cache its representation , All or part of it is quoted in other expressions , Add annotation information to it , Or do something about it ”,（ Derived from 《 The architecture of the World Wide Web 》）, You should define it as a resource .

Every resource must have URL, stay web On , We use URL To provide each resource with a unique global address , To ascribe to something URL, It will become a resource .

Pomegranate can be a resource , But you can't transmit it over the Internet , A record in a database can be a resource , And it can be transmitted over the Internet .

When a client initiates a Get On request , The server responds by providing a document that collects resource information in an efficient way . This kind of document of resource information is a kind of expression , A machine-readable description of the current state of a resource

There are multiple representations of resources

A resource can be expressed in many ways . such as , Some resources can be expressed in general terms , There can also be a detailed description of everything , Or maybe with JSON Format or XML Format to express the same resource .

Connection of resources

We know REST It's using standard HTTP Method to manipulate resources , But just because of that it's understood as a belt CURD Of Web Database architecture is too simple .

This antipattern ignores a core concept ：“ Hypermedia is the application state engine （hypermedia as the engine of application state）”. What is hypermedia ?

When you browse Web Web page time , Jump from a link to a page , Then jump from another link to another page , It's using the concept of hypermedia ： Link one resource to another .

To achieve this goal , It is required to add a link in the presentation format to guide the client . stay 《RESTful Web Services》 In a Book , The author calls this characteristic of link as connectivity . Let's take a look at some examples .

What is shown below is github Request to get a list of items under an organization , You can see that in the response header Link The header tells the client how to access the next and last page of records . And in the response body , use url To link the project owner to the project address .

The example above shows how to use hypermedia to enhance resource connectivity . A lot of people are designing RESTful Architecture , Spend a lot of time looking for beautiful URI, And ignore hypermedia . therefore , It should take more time to provide links to resource representations , Rather than focusing on " Resources CRUD".

The transfer of state

Visit a website , It represents an interactive process between the client and the server . In the process , It's bound to involve changes in data and state ;

Internet communication protocol HTTP agreement , It's a stateless protocol . It means , All States are saved on the server side . therefore , If the client wants to operate on the server , By some means , Let it happen on the server side " State transformation "（State Transfer）. And this transformation is based on the presentation layer , So is " Represent layer state transformation ";

The means used by the client , Can only be HTTP agreement . say concretely , Namely HTTP In the agreement , Four verbs for operation ：GET、POST、PUT、DELETE. They correspond to four basic operations ：GET Used to obtain resources ,POST Used to create a new resource （ Can also be used to update resources ）,PUT Used to update resources ,DELETE Used to delete resources ;

Blogger GitHub Address

https://github.com/yuyue5945

Pay attention to the official account