Restful API 的设计规范

发布时间：2020-12-14 05:12:16 所属栏目：百科来源：网络整理

导读：Restful API 的设计规范 1. URI URI规范资源集合 vs 单个资源避免层级过深的URI 对Composite资源的访问 2. Request HTTP方法安全性和幂等性复杂查询 Bookmarker Format Content Negotiation 6. Response 分页response 7. 错误处理 8. 服务型资源 9. 异步

Restful API 的设计规范 1. URI URI规范资源集合 vs 单个资源避免层级过深的URI 对Composite资源的访问 2. Request HTTP方法安全性和幂等性复杂查询 Bookmarker Format Content Negotiation 6. Response 分页response 7. 错误处理 8. 服务型资源 9. 异步任务 10. API的演进版本 URI失效 11. 安全参考文档本文总结了 RESTful API 设计相关的一些原则，只覆盖了常见的场景。有些规则只是针对自己项目而言，并非其他做法都是错误的。 1. URI URI 表示资源，资源一般对应服务器端领域模型中的实体类。 URI规范不用大写；用中杠`-`不用下杠`_`；参数列表要encode； URI中的名词表示资源集合，使用复数形式。资源集合 vs 单个资源 URI表示资源的两种方式：资源集合、单个资源。资源集合： /zoos //所有动物园 /zoos/1/animals //id为1的动物园中的所有动物单个资源： /zoos/1 //id为1的动物园 /zoos/1;2;3 //id为1，2，3的动物园避免层级过深的URI `/`在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。过深的导航容易导致url膨胀，不易维护，如?`GET /zoos/1/areas/3/animals/4`，尽量使用查询参数代替路径中的实体导航，如`GET /animals?zoo=1&area=3`；对Composite资源的访问服务器端的组合实体必须在uri中通过父实体的id导航访问。组合实体不是first-class的实体，它的生命周期完全依赖父实体，无法独立存在，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。一个常见的例子是 User — Address，Address是对User表中zipCode/country/city三个字段的简单抽象，无法独立于User存在。必须通过User索引到Address：`GET /user/1/addresses` 2. Request HTTP方法通过标准HTTP方法对资源CRUD： GET：查询 GET /zoos GET /zoos/1 1/employees POST：创建单个资源。POST一般向“资源集合”型uri发起 PUT /animals/1 PUT /zoos/1 DELETE：删除 ?type=1&age=16	允许一定的uri冗余，如`/zoos/1`与`/zoos?id=1`
排序	?
投影	分页	?

Bookmarker

经常使用的、复杂的查询标签化，降低维护成本。

如：

GET /trades?status=closed&sort=created,desc

快捷方式：

POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24

{   
  "name": "Gir","animalType": "12"
}

Content-Type: application/x-www-form-urlencoded?(浏览器POST表单用的格式)

POST /login HTTP/1.1
Host: example.com
Content-Length: 31
Accept: text/html
Content-Type: application/x-www-form-urlencoded

username=root&password=Zion0101

Content-Type: multipart/form-data; boundary=—-RANDOM_jDMUxq4Ot5?(表单有文件上传时的格式)

Content Negotiation

资源可以有多种表示方式，如json、xml、pdf、excel等等，客户端可以指定自己期望的格式，通常有两种方式：

http header?Accept：

Accept:application/xml;q=0.6,application/atom+xml;q=1.0

q为各项格式的偏好程度

url中加文件后缀：/zoo/1.json

6. Response

不要包装：?
response 的 body 直接就是数据，不要做多余的包装。错误示例：
```
{
    "success":true,"data":{"id":1,116);">"name":"xiaotuan"},}
```

各HTTP方法成功处理后的数据格式：

·	response 格式
GET	单个对象、集合
POST	新增成功的对象
PUT/PATCH	更新成功的对象
DELETE	空

json格式的约定：
1. 时间用长整形(毫秒数)，客户端自己按需解析（moment.js）
2. 不传null字段

分页response

GET /search?q=filter?category=file  搜索
GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448
POST /batch-publish-msg
[{"from":"to":"text":"abc"},{}...]

9. 异步任务

对耗时的异步任务，服务器端接受客户端传递的参数后，应返回创建成功的任务资源，其中包含了任务的执行状态。客户端可以轮训该任务获得最新的执行进度。

提交任务：
POST /batch-publish-msg
[{...]

返回：
{"taskId":3,116);">"createBy":"Anonymous",116);">"status":"running"}

GET /task/3
{"success"}

如果任务的执行状态包括较多信息，可以把“执行状态”抽象成组合资源，客户端查询该状态资源了解任务的执行情况。

GET /v1/users/1

Accept Header：Accept: application/json+v1

自定义 Header：X-Api-Version: 1

用第一种，虽然没有那么优雅，但最明显最方便。

URI失效

随着系统发展，总有一些API失效或者迁移，对失效的API，返回404 not found 或 410 gone；对迁移的API，返回 301 重定向。

11. 安全

这个不熟，接触到的时候再说。

参考文档

< RESTful Web Services Cookbook >
Consumer-Centric API Design
RESTful Best Practices

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!