当前位置：首页 > article >正文

简述RESTFul风格的API接口

article 2024/10/20 5:07:11

传统的风格API

REST风格

谓词规范

URL命令规范

避免多级URL

幂等

CURD的接口设计

REST响应

响应成功返回的状态码

重定向

错误代码

客户端

服务器

RESTful的返回格式

返回格式

从上一篇文章我们已经初步知道了怎么在VS中创建一个webapi项目。这篇文章来探讨一下啊什么是RESTFult风格的API接口。

传统的风格API

加入要获取单个用户——>/User/GetUser

对用户进行更新——>/User/UpdateUser

删除用户——>/User/DeleteUser

然后我去查阅资料，发现接口文档都有一下特征

1、接口Url地址；

2、Post、Get请求方式

3、请求参数

4、返回参数

5、返回格式：Json、Xml、Text等。

如果不是团队开发，自己写一写其实也还好，只要看得懂就行。

但是团队开发，都会有一套规范。这套规范去约束了我们

1.使用Get、Add、Update、Delete开头用来命令API接口，表示获取、插入、更新、删除的操作。

2.携带参数指定返回的格式，?type=json表示返回json格式，?type=xml表示返回xml格式。等。

REST风格

REST，即Representational State Transfer的缩写，翻译成中文”表现层状态转化。

具体如下：

1）资源，每一个资源都有指定的URL，要对资源进行操作，都是访问这个URL。

2）表现层，返回给前端的内容格式，是json，xml还是html等

1、?type=json表示返回json格式，?type=xml表示返回xml格式。

2、xxx.html表示返回html格式。

3、xxx.png表示返回png。

在REST定义里，应该在HTTP请求的头信息里面：Accept和Content-Type，这两个字段才是用来描述“表现层”的返回格式。

3）状态转化，对资源进行操作，就是状态转化，在REST里，用HTTP协议的谓词来表示，比如

GET、POST、PUT、DELETE，分别表示获取资源、新建资源、更新资源、删除资源。

说了这么多定义，REST风格的接口是有如下规范

谓词规范

1、GET 获取资源；

2、POST 新建/插入/添加资源；

3、PUT 更新资源（更新所有字段）；

4、DELETE 删除资源；

5、PATCH 部分更新资源部分字段。

URL命令规范

REST中的URL，必须是名词

比如

GET        /Users/Id        //获取用户
GET        /Users            //获取用户列表
POST      /Users       //添加用户
PUST       /Users/Id      //更新用户
DELETE    /Users/ID     //删除用户

避免多级URL

也就是防止出现多个/，针对需要较多过滤信息的，可以通过API的参数形式，过滤返回结果。

幂等

在REST也是有明确规定的。

1、安全、幂等：GET、HEAD、OPTIONS。

2、非安全、非幂等：POST、PUT、DELETE、PATCH。

CURD的接口设计

在REST对CRUD有了明确的规范定义，但是我们实际业务系统是非常复杂的，往往REST是无法满足我们的要求的。这个时候需要根据业务逻辑去抽取对外的接口。

REST响应

响应成功返回的状态码

GET: 200 OK

POST: 201 Created

PUT: 200 OK

PATCH: 200 OK

DELETE: 204 No Content

重定向

302会自动跳转，303不会自动跳转。

错误代码

客户端

400 Bad Request：服务器不理解客户端的请求，未做任何处理。

404 Not Found：所请求的资源不存在，或不可用。

401 Unauthorized：用户未提供身份验证凭据，或者没有通过身份验证。

403 Forbidden：用户通过了身份验证，但是不具有访问资源所需的权限。

405 Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内。

410 Gone：所请求的资源已从这个地址转移，不再可用。

415 Unsupported Media Type：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式。

422 Unprocessable Entity ：客户端上传的附件无法处理，导致请求失败。

429 Too Many Requests：客户端的请求次数超过限额。