清平の乐

REST API设计规范

这里整理的REST API的设计规范，注意和后端开发的API接口文档做一下区分，不是一个概念。API是REST API的超集，REST API 是API的子集；所有的REST API都是API，但不是所有的API都是REST API

一、公共要求

API通常使用HTTPs协议，确保交互数据的传输安全，域名尽量将api部署在专用域名下https：//api.example.com，具体公共要求如下

1.在URI中使用小写字母，不要采用驼峰命名。

方便时，在URI路径中应始终首选小写字母。

http://api.example.org/my-folder/my-doc

2.使用名词来表示资源

URI只包含只能包含名词较好，应该引用作为事物（名词）的资源，而不是引用动作（动词）

3.使用正斜杠（/）表示层次关系，URI结尾不要带正斜杠（/）

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

4.使用连字符（-）来提高URI的可读性，不要使用下划线（_）

下划线（_）字符可能会被部分遮挡或在某些浏览器或屏幕中完全隐藏。

//可读性强
http://api.example.com/{id}/install-script-location 

//更多容易出错
http://api.example.com/{id}/install_script_location

5.不要在URI中使用CRUD函数名称

URI不应用于指示执行CRUD功能。URI应该用于唯一标识资源，而不是对资源进行任何操作。应该使用HTTP请求方法来指示执行了哪个CRUD功能。

HTTP GET http://api.example.com/device-management/managed-devices //获取所有设备
HTTP POST http://api.example.com/device-management/managed-devices //创建新设备

HTTP GET http://api.example.com/device-management/managed-devices/{id} //获取给定ID的设备
HTTP PUT http://api.example.com/device-management/managed-devices/{id} //更新给定ID的设备
HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //删除给定ID的设备

6.杜绝完全不规范的缩写，尽量见明知意避免望文生义

7.不要使用文件扩展名

如果要使用文件扩展名突出显示API的媒体类型，则应依靠通过Content-Type标头传达的媒体类型来确定如何处理正文内容。

//错误示范
http://api.example.com/device-management/managed-devices.xml 

//这是正确的URI
http://api.example.com/device-management/managed-devices

二、资源命名

通过对"资源"操作(读、写、通知)的依赖实现业务领域之间的依赖。API作为"业务领域"间沟通的手段，应该以面向资源角度进行命名。

1.单个资源：可以是一个单体或集合

例如，customers是集合资源， customer是单例资源。我们可以customers使用URI /customers来标识集合资源。我们可以customer使用URI“ /customers/{customerId}” 来标识单个资源。

个人建议当API来源为跨源SQL或者跨库关联可以用集合，单个表或者库可以用单体模式。

2.子资源

根据公司现状可以和业务或者需求确定好大的分类，确定2-4级分类

2.1.业务域方面

主资源名称根据业务域进行划分（具体的和抽象的），子资源可附加业务需求、对象。子资源需要逐级索引命名，

（1）具体的数据对象：

商品 goods
产品 products
订单 order
合同 …

（2）抽象的对象概念：

电商
客户（用户）
预算
物流 …

2.2渠道方面

（1）内部

inner
user

（2）外部

PC
app
customer
store

3.版本控制

如果后期公司涉及到版本更新可以再最初或者第二次开始添加版本参数，将版本号放在url中或者header中 v1，v2，vn…

三、参数

目前参数支持：integer,number,boolean,string

API契约应该由”API名 + 入参”共同组成，参数动词和名词可做一下统一规范

条目 item
特性 feature
金额 amount
。。。

很多时候，您会遇到需求，其中您将需要根据某些资源属性对资源进行排序，过滤或限制的集合。为此，请勿创建新的API，而应在资源收集API中启用排序，过滤和分页功能，并将输入参数作为查询参数传递。例如

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=美国
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ

四、响应体

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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

其它补充：

（1）过滤信息：？limit=10 ？offset=10 ？page=1 ？sortby=name

（2）Hypermedia Api：在返回结果中提供相关资源的连接，连向其他Api方法

（3）验证：确定用户是其声明的身份，比如提供账户的密码

（4）授权：保证用户有对资源特定操作的权限。比如用户私人信息只能自己能够访问，其他人无法看到，有些特殊的操作只能管理员可以操作，其他用户有只读的权限等

参考文档：
深入理解什么是RESTful API ？
RESTful API 设计指南
正确甄别API、REST API、RESTful API和Web Service之间的异同
REST API教程