Restful HTTP API 设计

1、地址(Https)

API前缀记得分版本

https://example.com/api/v1

2、以Http动词定义操作

• GET（SELECT）：从服务器取出资源。获取单个资源，分页列表等等
• POST（CREATE）：在服务器新建一个资源
• PUT（UPDATE）：在服务器更新资源，更新资源所有属性
• PATCH（UPDATE）：在服务器更新资源，更新资源部分属性
• DELETE（DELETE）：从服务器删除资源

对应地址举例：

• GET https://example.com/api/v1/user：列出所有用户
• POST https://example.com/api/v1/user：新建一个用户
• GET https://example.com/api/v1/user/{userId}：获取某个指定用户的信息
• PUT https://example.com/api/v1/user/{userId}：更新某个指定用户的信息（提供该用户的全部信息）
• PATCH https://example.com/api/v1/user/{userId}：更新某个指定用户的信息（提供该用户的部分信息）
• DELETE https://example.com/api/v1/user/{userId}：删除某个用户
• GET https://example.com/api/v1/user/{userId}/friends：列出某个指定用户的所有好友
• GET https://example.com/api/v1/user/{userId}/friend?page=1&size=20：列出某个指定用户的第一页好友
• DELETE https://example.com/api/v1/user/{userId}/{friendId}：某个指定用户删除某个好友

注意：路径参数不要传字符串，可能存在"/"之类的特殊字符
这里提下POST与PUT的区别：幂等性

• 幂等性：两次或多次同样的操作造成的结果是一样的就是幂等的

GET，PUT，DELETE都是幂等操作，而POST不是。
GET查询，不管查询多少次，结果都是一样的。DELETE删除，第一次删除了资源，第二次再提交同样的参数去删除，也是一样的，只是第二次没起作用，该资源已经不存在了而已。同理PUT提交同样的参数去更新同一个资源。都是幂等的。
POST不是幂等操作，因为一次请求添加一份新资源，二次请求则添加了两份新资源，多次请求会产生不同的结果，因此POST不是幂等操作。
用Http动词来设计API动作。

3、定义合适的Http返回状态码

200 OK
请求正常处理完毕
204 No Content
请求成功处理，无数据返回
206 Partial Content
GET范围请求已成功处理
301 Moved Permanently
永久重定向，资源已永久分配新URI
302 Found
临时重定向，资源已临时分配新URI
303 See Other
临时重定向，期望使用GET定向获取
304 Not Modified
发送的附带条件请求未满足
307 Temporary Redirect
临时重定向，POST不会变成GET
400 Bad Request
请求报文语法错误或参数错误
401 Unauthorized
需要通过HTTP认证，或认证失败
403 Forbidden
请求资源被拒绝
404 Not Found
无法找到请求资源（服务器无理由拒绝）
500 Internal Server Error
服务器故障或Web应用故障
503 Service Unavailable
服务器超负载或停机维护

4、结合Swagger2查看、测试API文档

最近还发现个好东西：eolinker