What is restful and what rules should be followed when designing rest APIs?

As a developer , I believe you all know that “REST” This term , however  REST  What does that mean? , What is?  RESTful  service ？ Today, I will take you to have a good understanding of  RESTful.

What is? REST？

• English full name ：
  Representational State Transfer

• Chinese meaning ： Presentation layer state transition

REST Is a client application （ That's the front end ）, Use  

HTTP

  Deal with the  Web  service （ Back end ） Interact to create 、 Delete 、 Update and delete data （

CRUD

  operation ） The process of .

REST  It's by computer scientists  Roy Fielding  Defined , He was in  2000  In his doctoral thesis in, he introduced  REST  principle .

accord with  REST  The system of , Often referred to as  RESTful  System , Its characteristic is that they are

No state

Of , And separate the concerns of the client and the server , namely

Fore and aft end separation

.

Fore and aft end separation

When there is no front and rear end separation , Developers are very painful , This is like a company with only one boss , financial 、 Business 、 product 、 Technology should be concerned about everything , And no matter front-end or back-end , A little change will affect each other , test 、 Maintenance costs are huge .

stay  REST  Architecture style , The implementation of client and server can

Independent

complete , They don't know each other . This means that the client code can be changed at any time without affecting the operation of the server , The server-side code can be changed without affecting the operation of the client .

As long as both parties know the message format to be sent to each other , They can keep

modularization

and

Separate

, Separate user interface concerns from data storage concerns , This can greatly improve the flexibility of the cross platform interface , And improve scalability by simplifying server components .

This is the advantage of front and rear end separation .

How to use REST API？

HTTP  Verb

REST API  Through a variety of  HTTP  Request method , Make the communication process between the front end and the server easier , The most common method is ：

• GET
   :  Used to read data from the server .

• POST
   :  Used to create data .

• PATCH
  /
  PUT
  ： Used to update data .

• DELETE
   :  Used to delete data .

route

The request must contain a path to the resource on which the operation should be performed .

stay RESTful In style , The following principles should be observed ：

1. URL  It should contain nouns , Not verbs

For example, get the user list , The right is ：

https://www.wljslmz.cn/users


The wrong is ：

https://www.wljslmz.cn/getUsers


2、URL Use the plural , Not singular

Or the example above , Get the list of users , The right is ：

https://www.wljslmz.cn/users


The wrong is ：

https://www.wljslmz.cn/user


3、URL It is better to include the version number in the , If do not have , It should be considered as the latest edition , Not the stable version

such as ：

https://www.wljslmz.cn/v1/users


4、URL Use nesting to display relationships in

Like getting id by 1 User information for ：

https://www.wljslmz.cn/v1/users/1


5、URL Pagination

Paging can easily handle a large number of request results , for example ,Web  The service contains hundreds or thousands of pages , When a request is made to display all its pages , Will get the same number of results in response .

For example, the user information list is displayed in pages ：

https://www.wljslmz.cn/v1/users/page=1?limit=10


6、 Use hyphens to increase readability

Better use hyphens -, instead of _ Or a hump , In all  RESTful API  in , Hyphens are equivalent to spaces .

Such as user id by 1 Users of start working ：

https://www.wljslmz.cn/v1/users/1/start-work


7、URL It is better not to use capital letters

Defining resources in uppercase letters makes  URL  Key sensitive , May cause confusion under certain circumstances , Using lowercase letters will ensure the correctness of the command , Even if  URL  It is typed in capital letters , But not the other way around ：

For example, the first 6 individual url It's better not to write ：

https://www.wljslmz.cn/v1/users/1/Start-Sork


You write like this ：

https://www.wljslmz.cn/v1/users/1/start-work


Even if you type ：

https://www.wljslmz.cn/v1/users/1/Start-Sork

, It will also match correctly

https://www.wljslmz.cn/v1/users/1/start-work

.

But if api yes

https://www.wljslmz.cn/v1/users/1/start-work

, Then you must be capitalized in the browser .

common  HTTP  Status code

• 1xxs： Information response , The server is still processing the request .

• 2xxs： success , Request completed successfully

• 3xxs： Redirect , The received request is redirected to another address .

• 4xxs： Client error , for example ,404 -  Page not found .

• 5xxs： Server error , request was aborted .

Some common  HTTP  Status codes include ：

• 200
  ： A successful request , Usually  GET

• 201
  ： The request is successful after creation , Usually  POST

• 204
  ： The request is successful , No content returned , Usually  PUT  or  PATCH

• 301
  ： Permanently redirect to another endpoint

• 400
  ： Wrong request （ The client should modify the request ）

• 401
  ： unaccredited , The credentials are not recognized

• 403
  ： prohibit , Credentials accepted without permission

• 404
  ： Not found , Resource does not exist

• 410
  ： Vanished , The resource existed before but does not exist now

• 429
  ： Too many requests , For rate limiting , Should contain retry header

• 500
  ： Server error , generality , It's worth checking out other  500  Level error

• 503
  ： Service not available , Another retry header is useful

summary

REST Is a software architecture style , be used for  Web  Architecture design , Any compliance  REST  Design principles  API They are all called  RESTful, At the beginning of development , Developers need to spend a lot of time designing interfaces , These interfaces generally follow RESTful style , Strive to make the interface simple 、 Understandability .