RESTful 实践 2021-11-02

1. URL 设计

1.1 动词 + 宾语

一切请求的数据都是资源，动词就是请求方式，宾语就是资源，资源一律用复数形式

• GET：读取资源
  • GET /accounts 读取所有用户
  • GET /accounts/{id} 读取指定用户
• POST：新建资源
  • POST /accounts 新建一个用户
• PUT：更新资源
  • PUT /accounts/{id} 更新指定用户信息（提供该用户全部信息）
• PATCH：更新部分资源
  • PATCH /accounts/{id} 更新指定用户信息（提供更新的信息）
• DELETE：删除资源
  • DELETE /accounts/{id} 删除指定用户

如果有些客户端只能发送GET和POST请求，可以在请求中加上X-HTTP-Method-Override属性指定具体请求方式，覆盖POST

2. 状态码

返回的状态码必须精确

• 1xx：相关信息
• 2xx：操作成功
• 3xx：重定向
• 4xx：客户端错误
• 5xx：服务器错误

2.1 2xx

• GET：200 OK
• POST：201 创建成功
• PUT：200 OK
• PATCH：200 OK
• DELETE：204 No Content

2.2 4xx

• 400：服务器不理解这个请求，未做任何处理
• 401：用户没提供身份凭证或者没有通过身份验证
• 403：用户通过了身份验证，但不具备访问资源需要的权限
• 404：资源不存在
• 405：用户通过了身份验证，但所用的HTTP方法不在他的权限之内
• 410：资源已从这个地址转移
• 415：客户端要求返回的格式不支持，比如接口返回的JSON，但客户端要接受XML
• 422：客户端上传的附件无法处理
• 429：客户端请求次数超过限额

2.3 5xx

• 500：服务器处理时发生故障
• 503：服务器无法处理请求，一般是网站在维护