REST 接口学习

Posted lucky-girl

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了REST 接口学习相关的知识,希望对你有一定的参考价值。

一、REST 接口

在请求层面,REST 规范可以简单粗暴抽象成以下两个规则:

请求 API 的 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

注意:这就是REST接口,用url定位资源,用HTTP描述操作

上面我们定义的四个接口就是符合REST协议的,请注意,这几个接口都没有动词,只有名词friends,都是通过Http请求的接口类型来判断是什么业务操作。

二、API的请求方法

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

CRUD 是指在做计算处理时的增加(Create)、读取查询(Retrieve)、更新(Update)和删除(Delete)几个单词的首字母简写。即增删改查

【Read】,资源的读取,用 GET 请求;比如:
GET /api/users  ( 表示读取用户列表)

GET 应当实现为一个安全方法。用于获取数据而不应该产生副作用。

【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 接口学习的主要内容,如果未能解决你的问题,请参考以下文章

hadoop学习笔记-HDFS的REST接口

Django REST框架--认证和权限

Kotlin学习之旅解决错误:kotlin.NotImplementedError: An operation is not implemented: Not yet implemented(代码片段

java中封装,继承,多态,接口学习总结

18-Django REST framework-使用Django开发REST 接口

从父片段到选项卡片段的接口侦听器不起作用