WebAPI规范

REST_IN_PRACTICE-WebAPI规范整理

WebAPI规范整理

Posted by Claire on August 1, 2020

WebAPI规范

一、协议

通常使用HTTPs协议

二、域名

API较简单，可将API放在主域名下，以固定prefix开头，例如：https://example.com/api/xxxx
API内容丰富，复杂多样，可将API部署在专属域名下，例如：https://api.example.com/

三、版本控制

使用场景

客户端无法及时更新当应用客户端不能及时更新，为兼容客户端用户侧的使用，需要将接口版本化，以便不同版本的应用都能够正常使用；
提供标准的第三方接口当需要向第三方提供标准接口时，鉴于长远的发展，功能的迭代更新，都必须要设置API版本控制；

使用方法

使用大版本URL形式，小版本Header形式，进行版本标识

URL标识形式大版本标识不向前兼容类型，比如方法的参数形式有了变化、方法名有了变等，不能与之前的API兼容的，采用URL标识形式，例如：http://example.com/api/v1/xxx;
Header标识形式小版本标识向前兼容类型，比如方法添加了参数，之前的方法不影响使用，仅通过Header的标识具体小版本即可，例如：Header内部 API-VERSION:1.2.1

四、URI设计

Http动词+宾语
- GET：读取（Read）
- POST：新建（Create）
- PUT：更新（Update）
- PATCH：更新（Update），通常是部分更新
- DELETE：删除（Delete）
宾语通常采用名词复数形式
- 例如 GET /api/articles
- 例如 DELETE /api/articles/{id}

五、状态码

需要针对每一个Request，给出HTTP状态码的反馈，不是正确错误都是200的响应，可以内部自定义业务code来表示具体的含义。

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

六、结果响应

响应Content-Type API通常以“application/json;charset=utf-8”的形式来响应接口，牺牲了少许网络传输的效率，大大提升结果的可读性，也是业内前后端交互认可的方式。
方法响应结果规范

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

参考列表