通用设计规则

资源：往往对应着后台系统中对象，比如一个用户User，一个待办事项todo item，一个任务Task等等

用对应的接口表示要对资源进行何种操作，想要实现什么目的：

举例：RESTful的某个类似于外卖的项目的API

此处给出之前做过一个项目的RESTful的API，供参考：

• 用户
  • 获取用户ID：支持多个参数，根据参数不同返回对应的值
    • GET /v1.0/open/userId?type=phone&phone={phone}
    • GET /v1.0/open/userId?type=email&email={email}
    • GET /v1.0/open/userId?type=facebook&facebookUserId={facebookUserId}
  • 获取用户信息
    • GET /v1.0/users/{userId}
  • 修改用户信息
    • PUT /v1.0/users/{userId}/info
  • 修改密码
    • PUT /v1.0/users/{userId}/password
• 订单
  • 获取订单任务信息
    • GET /v1.0/tasks/{taskId}/users/{userId}
  • 发布任务
    • POST /v1.0/tasks/users/{userId}
  • 发单人确认任务信息
    • PUT /v1.0/tasks/{taskId}/users/{userId}/confirmInfo

常见问题

在具体设计接口时，会遇到一些具体的某些接口，到底应该用哪个HTTP的方法等方面的问题，整理如下供参考：

更新资源到底应该用PATCH还是PUT?

对于更新一个资源，很多人都会遇到这个问题，到底应该用PATCH还是PUT？

现解释如下：

HTTP的官方规范定义中，其实是：

举例说明

有一个user用户，信息是：

{
  "name": "zhangsan",
  "email": "[email protected]"
}

按照PUT的规范来说，如果想要更新这个用户的邮箱，则需要传递：

PUT /user/some_user_id

{
  "name": "zhangsan",
  "email": "[email protected]"
}

否则如果传递：

PUT /user/some_user_id

{
  "email": "[email protected]"
}

REST标准中PUT就会认为，你没有其他字段，包括name，则会去设置name为null

-> 这样才是原本想要的replace替换的效果

而如果只是想要更新用户邮箱，应该去用PATCH，传递：

PATCH /user/some_user_id

{
  "email": "[email protected]"
}

然后才可以实现：只更新email字段，保留其他字段的已有的值

但是现在实际上大部人都是为了省事，也可以说作为最佳实践，用PUT代替PATCH，传入

PUT /user/some_user_id

{
  "email": "[email protected]"
}

去实现（只）更新email邮箱，而保留其他（比如用户名name）的效果。

POST创建资源成功后是返回200还是201?

虽然按照REST协议来说，POST了新建的，应该返回201

但是为了统一处理，以及：很多开发者未必能很好的处理201，所以：

对于操作成功的，都正常返回200即可。

然后在response中返回对应的信息

比如：

新建的对象的详细信息

或者只是新建对象的id

结论：

• HTTP协议规范：POST创建成功后，应该返回201，以及对应的新的资源的id
  • 用户再通过新建资源的id，去获取资源详情
• 最佳实践：大家实际的常见做法则是，直接返回新建资源的所有的详情的json，其中包括id

DELETE应该返回什么？

综合官网和其他文档后，REST服务器端对于DELETE请求应该返回什么状态码，以及具体返回什么值，详细解释如下：

• 202=Accepted：表示接受了此删除请求
  • 但是暂时还没执行
  • 或者目前执行删除动作，但是还没有完成
    • 之后（服务器端）会完成删除动作
• 204=No Content：已经执行了删除动作，内容被删除了，没有内容了
  • response的body中是空的
  • 注意：如果要实现HATEOAS的REST的接口，则尽量避免DELETE返回204
    • 详见：rest - RESTful API: Delete Entity - What should I return as result? - Stack Overflow
• 200=OK：内容已删除，同时返回body信息，包含具体的删除的详情
  • response的body中包含额外关于删除的相关信息
    • 比如之前帖子中提到的，删除了具体哪个内容，已删除的状态，甚至删除了符合对应条件的多个内容等等

目前自己所理解的最佳实践是第三种：

• 返回状态码：200=OK
• 返回什么值：根据之前的最佳实践：code、message、data，应该返回：

{
  "code": 200,
  "message": "Question deleted for id 5c1777e1cc6df4563adf4a50",
  "data": {
    "deletedCount": 1
  }
}

且更加细节的做法是：当检测到想要删除一个已经删除的内容，则提示已经删除了：

{
  "code": 200,
  "message": "Question already deleted for id 5c1777e1cc6df4563adf4a50",
  "data": {
    "deletedCount": 0
  }
}