REST api 设计风格

1、什么是 REST 的设计风格

REST是一种面向资源URL设计风格，URL地址表示资源（也就是一个名词），而请求的方法对应对资源的操作，URL中不会出现动词，例如：

请求含义	错误	正确
获取所有小狗狗	GET /rest/api/getDogs	GET /rest/api/dogs
添加一个小狗狗	GET /rest/api/addDogs	POST /rest/api/dogs
修改一个小狗狗	GET /rest/api/editDogs/:dog_id	PUT /rest/api/dogs/:dog_id
删除一个小狗狗	GET /rest/api/deleteDogs/:dog_id	DELETE /rest/api/dogs/:dog_id

REST 的动词

对于crud四种任务，REST使用以下5种动词，对应不同的请求方法：

• GET：取出资源
• POST：新建资源
• PUT：更新资源（提供完整的更新体）
• PATCH：更新资源（只提供修改部分）
• DELETE：删除资源

对于比较复杂的任务，Non-CRUD的操作，REST可以在路径上增加"action?action-id=XXX"的形式，对应 POST /资源/action作为URL，并将操作放在body体中。

优缺点：

• 优点：容易理解
• 缺点：设计变得比较复杂

2、路径规范：

• 结尾不包含/：https://api.example.com/v1/hosts（正确）https://api.example.com/v1/hosts/（错误）
• /用于指示层级关系
• 连接符用-：例如：my-doc，不要使用_
• 使用小写字母，因为有一些规范不区分大小写
• 不要把扩展名放进路径，使用Content-Type传递格式

3、请求返回体

• 返回容易理解的JSON体
• 可以加入request-id标识请求的唯一性，方便追溯
• 支持Etag缓存

4、错误处理

生成结构化的错误信息：
包含一个机器可读的错误 id，一个人类可读的错误信息（message），根据情况可以添加一个URL来告诉客户端关于这个错误的更多信息以及如何去解决它。

例如：

HTTP/1.1 501 Not Implemented

{

    "error_code": "XXS.0005",

    "error_msg": "Service does not exist"

}