Restful API 接口设计规范

引言：

##  Restful API是根据REST架构原则设计的接口规范，由这个接口规范倡导的命名规范以及请求规范。

---

涉及知识点：

REST架构

 

• 由  ↓   创立：

• “一切皆资源”为前提：资源可以是一个图片、音乐、一个XML格式、HTML格式或者JSON格式等网络上的一个实体，除了一些二进制的资源外普通的文本资源更多以JSON为载体、面向用户的一组数据(通常从数据库中查询而得到)

• 统一接口: 对资源的操作包括获取、创建、修改和删除，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。换言而知，使用RESTful风格的接口但从接口上你可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断 。

---

1. 概念

Restful APIRESTful是目前最流行的接口设计规范，基于HTTP请求开发；

官网地址：Reqres - A hosted REST-API ready to respond to your AJAX requestsA hosted REST-API ready to respond to your AJAX requestshttps://reqres.in/

2. request url规范

/api/资源?id=请求参数

***资源解释：

一般代表资源都是以复数的形式出现，但也有例外，如果是表示一些动作如登录、注册则不需要写成复数

3.  restful api 实例

   

Request					Response
请求方式	注释 (en)	请求url	请求参数	注释 (zh)	返回状态;	返回数据
GET	LIST USERS	/api/users?page=2		获取用户列表	200	{ "page": 2, "per_page": 6, "total": 12, "total_pages": 2, "data": [ { "id": 7, "email": "michael.lawson@reqres.in", "first_name": "Michael", "last_name": "Lawson", "avatar": "https://reqres.in/img/faces/7-image.jpg" }, { "id": 8, "email": "lindsay.ferguson@reqres.in", "first_name": "Lindsay", "last_name": "Ferguson", "avatar": "https://reqres.in/img/faces/8-image.jpg" }, { "id": 9, "email": "tobias.funke@reqres.in", "first_name": "Tobias", "last_name": "Funke", "avatar": "https://reqres.in/img/faces/9-image.jpg" }, { "id": 10, "email": "byron.fields@reqres.in", "first_name": "Byron", "last_name": "Fields", "avatar": "https://reqres.in/img/faces/10-image.jpg" }, { "id": 11, "email": "george.edwards@reqres.in", "first_name": "George", "last_name": "Edwards", "avatar": "https://reqres.in/img/faces/11-image.jpg" }, { "id": 12, "email": "rachel.howell@reqres.in", "first_name": "Rachel", "last_name": "Howell", "avatar": "https://reqres.in/img/faces/12-image.jpg" } ], "support": { "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests", "text": "To keep ReqRes free, contributions towards server costs are appreciated!" } }
GET	SINGLE USER	/api/users/2		获取用户详情	200	{ "data": { "id": 2, "email": "janet.weaver@reqres.in", "first_name": "Janet", "last_name": "Weaver", "avatar": "https://reqres.in/img/faces/2-image.jpg" }, "support": { "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests", "text": "To keep ReqRes free, contributions towards server costs are appreciated!" } }
GET	SINGLE USER NOT FOUND	/api/users/23		用户不存在	404	{}
GET	LIST <RESOURCE>	/api/unknown			200	{ "page": 1, "per_page": 6, "total": 12, "total_pages": 2, "data": [ { "id": 1, "name": "cerulean", "year": 2000, "color": "#98B2D1", "pantone_value": "15-4020" }, { "id": 2, "name": "fuchsia rose", "year": 2001, "color": "#C74375", "pantone_value": "17-2031" }, { "id": 3, "name": "true red", "year": 2002, "color": "#BF1932", "pantone_value": "19-1664" }, { "id": 4, "name": "aqua sky", "year": 2003, "color": "#7BC4C4", "pantone_value": "14-4811" }, { "id": 5, "name": "tigerlily", "year": 2004, "color": "#E2583E", "pantone_value": "17-1456" }, { "id": 6, "name": "blue turquoise", "year": 2005, "color": "#53B0AE", "pantone_value": "15-5217" } ], "support": { "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests", "text": "To keep ReqRes free, contributions towards server costs are appreciated!" } }
GET	SINGLE <RESOURCE>	api/unknown/2			200	{ "data": { "id": 2, "name": "fuchsia rose", "year": 2001, "color": "#C74375", "pantone_value": "17-2031" }, "support": { "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests", "text": "To keep ReqRes free, contributions towards server costs are appreciated!" } }
GET	SINGLE <RESOURCE> NOT FOUND	/api/unknown/23			404	{}
POST	CREATE	/api/users	{ "name": "morpheus", "job": "leader" }	创建用户	201	{ "name": "morpheus", "job": "leader", "id": "473", "createdAt": "2022-11-01T07:35:54.844Z" }
PUT	UPDATE	/api/users/2	{ "name": "morpheus", "job": "zion resident" }	修改用户	200	{ "name": "morpheus", "job": "zion resident", "updatedAt": "2022-11-01T07:38:34.189Z" }
PATCH	UPDATE	/api/users/2	{ "name": "morpheus", "job": "zion resident" }	修改用户	200	{ "name": "morpheus", "job": "zion resident", "updatedAt": "2022-11-01T07:40:25.996Z" }
DELETE	DELETE	/api/users/2		删除用户	204
POST	REGISTER - SUCCESSFUL	/api/register	{ "email": "eve.holt@reqres.in", "password": "pistol" }	注册用户成功	200	{ "id": 4, "token": "QpwL5tke4Pnpja7X4" }
POST	REGISTER - UNSUCCESSFUL	/api/register	{ "email": "sydney@fife" }	注册用户失败	400	{ "error": "Missing password" }
POST	LOGIN - SUCCESSFUL	/api/login	{ "email": "eve.holt@reqres.in", "password": "cityslicka" }	用户登录成功	200	{ "token": "QpwL5tke4Pnpja7X4" }
POST	LOGIN - UNSUCCESSFUL	/api/login	{ "email": "peter@klaven" }	用户登录失败	400	{ "error": "Missing password" }
GET	DELAYED RESPONSE	/api/users?delay=3			200	{ "page": 1, "per_page": 6, "total": 12, "total_pages": 2, "data": [ { "id": 1, "email": "george.bluth@reqres.in", "first_name": "George", "last_name": "Bluth", "avatar": "https://reqres.in/img/faces/1-image.jpg" }, { "id": 2, "email": "janet.weaver@reqres.in", "first_name": "Janet", "last_name": "Weaver", "avatar": "https://reqres.in/img/faces/2-image.jpg" }, { "id": 3, "email": "emma.wong@reqres.in", "first_name": "Emma", "last_name": "Wong", "avatar": "https://reqres.in/img/faces/3-image.jpg" }, { "id": 4, "email": "eve.holt@reqres.in", "first_name": "Eve", "last_name": "Holt", "avatar": "https://reqres.in/img/faces/4-image.jpg" }, { "id": 5, "email": "charles.morris@reqres.in", "first_name": "Charles", "last_name": "Morris", "avatar": "https://reqres.in/img/faces/5-image.jpg" }, { "id": 6, "email": "tracey.ramos@reqres.in", "first_name": "Tracey", "last_name": "Ramos", "avatar": "https://reqres.in/img/faces/6-image.jpg" } ], "support": { "url": "Reqres - A hosted REST-API ready to respond to your AJAX requests", "text": "To keep ReqRes free, contributions towards server costs are appreciated!" } }