REST 接口

REST 接口

在请求层面，REST 规范可以简单粗暴抽象成以下两个规则：
url定位资源
请求的method是对这个资源的操作。
知乎大神Ivony有句话说的好：
URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作
在设计web接口的时候，REST主要是用于定义接口名，接口名一般是用名词写，不用动词，那怎么表达“获取”或者“删除”或者“更新”这样的操作呢——用请求类型来区分。
比如，我们有一个friends接口，对于“朋友”我们有增删改查四种操作，怎么定义REST接口？

增加一个朋友，uri: generalcode.cn/v1/friends 接口类型：POST

删除一个朋友，uri: generalcode.cn/va/friends 接口类型：DELETE

修改一个朋友，uri: generalcode.cn/va/friends 接口类型：PUT

查找朋友，uri: generalcode.cn/va/friends 接口类型：GET

API请求方法

在很多系统中，几乎只用 GET 和 POST 方法来完成了所有的接口操作；这个行为类似于全用 DIV 来布局。实际上，我们不只有GET 和 POST 可用，在 REST 架构中，有以下几个重要的请求方法：GET，POST，PUT，PATCH，DELETE。这几个方法都可以与对数据的 CRUD 操作对应起来。
【Read】，资源的读取，用 GET 请求；比如：

GET /api/users  （ 表示读取用户列表）

【Created】，资源的创建，用 POST 方法；POST 是一个非幂等的方法，多次调用会造成不同效果；
【Update】，资源的更新。用于更新的 HTTP 方法有两个，PUT 和 PATCH。
他们都应当被实现为幂等方法，即多次同样的更新请求应当对服务器产生同样的副作用。

PUT 和 PATCH 有各自不同的使用场景：

PUT 用于更新资源的全部信息，在请求的 body 中需要传入修改后的全部资源主体；

而 PATCH 用于局部更新，在 body 中只需要传入需要改动的资源字段。

【Delete】，资源的删除，相应的请求 HTTP 方法就是 DELETE。这个也应当被实现为一个幂等的方法。

状态码

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

• 200 OK – [GET]：服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
• 201 CREATED – [POST/PUT/PATCH]：用户新建或修改数据成功。
• 202 Accepted – [*]：表示一个请求已经进入后台排队（异步任务）
• 204 NO CONTENT – [DELETE]：用户删除数据成功。
• 400 INVALID REQUEST – [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
• 401 Unauthorized – [*]：表示用户没有权限（令牌、用户名、密码错误）。
• 403 Forbidden – [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
• 404 NOT FOUND – [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
• 406 Not Acceptable – [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
• 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
• 422 Unprocesable entity – [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
• 500 INTERNAL SERVER ERROR – [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

今天的文章REST 接口分享到此就结束了，感谢您的阅读。