RESTful API 理解吸收笔记

执檀月夜游

于 2021-03-22 16:45:01 发布

阅读量149

点赞数

分类专栏： Web

本文链接：https://blog.csdn.net/kungFuApe/article/details/115084459

版权

Web 专栏收录该内容

3 篇文章 0 订阅

订阅专栏

熟读以下文章

通则

查询用GET /resources, 结果通常是多笔,也可能是单笔, 或是 0 笔
获取单笔一律用 uuid, GET /resources/{uuid}
url 用小写的 Kebab Case(用 - 來分隔單字), json 属性用小写的 Camel Case(駝峰)
新增的 API 可以视需求设计成可同时新增多笔 POST /orders [{order1}, {order2}, {order3}]
更新单笔通常使用 uuid, PATCH /resources/{uuid}, 无法用 UUID, 或者需要更新多笔时, 用PATH /resources
删除单笔通常使用 uuid,PATCH /resources/{uuid}, 无法用 UUID, 或者需要删除多笔时, 用 PATH /resources
URL 通常格式为模组(3 个字元)/资源(复数)/识别码(uuid), ex:
/pso/orders/d8f1f4fe-38d1-4b0c-afa0-4af475502d27
单头/单身分开处理, 不要在同一个 API 有单头/单身的结构 ex:
/orders/123/items,/orders/123/items/456
多笔的数据输入用 array, 不要用 "逗号分隔字串"的方式
特殊的操作通常是属于 resource archetypes 的 controller type, 在 url 最后一个 segment 用动词描述

 A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

 Use “verb” to denote controller archetype.

 http://api.example.com/cart-management/users/{id}/cart/checkout
 http://api.example.com/song-management/users/{id}/playlist/play

多笔查询需要返回其他关联表的字段时,只返回必要的字段

select a.*
, b.uuid
, b.no
, b.name
, c.uuid
, c.no
, c.name
, c.type -- b.xxx, c.xxx 不得超过5个

left join b
left join c

PATCH (PUT) API 的设计方式

如果订单的更新操作包含以下三个业务逻辑

指派负责人员: 更新 agent
审核: 更新 confirm 字段为 true
拒绝: 更新 confirm 字段为 false

通常是使用 PATCH orders/{uuid}对一笔订单做更新. 这个是通用性的更新操作, 可能是订单里的任何字段做更新的操作

如果逻辑不复杂,可以直接用上面的一个 API URL 处理

指派负责人员: PATCH /orders/123 { “agent” : “luce” }
审核: PATCH /orders/123 { “confirm” : true }
拒绝: PATCH /orders/123 { “confirm” : false }
同时处理指派负责人员 + 审核 : PATCH /orders/123 { “agent” : “luce”, “confirm”: true }

但是如果业务逻辑比较复杂时,在同一个 API 处理太多逻辑,代码会变得很难管理; API 也容易被误用. 针对这样的情况, 可以在 PATCH API 加上一个后缀, 明确的区分一般的更新以及这三个操作的区分. 让原本的一个 API 变成 4 个独立的 API 处理

指派负责人员: PATCH /orders/123/assign { “agent” : “luce” }
审核: PATCH /orders/123/approved { “confirm” : true }
拒绝: PATCH /orders/123/rejected { “confirm” : false }
其他一般更新: PATCH /orders/123 { “phone”: “12345678”, “address”: “地址信息…” }

orders/123/{操作名称} 是在订单资源(uuid=123)后面加上一个操作名称, 用来区别不同的更新逻辑. 这样就可以让 PATCH /orders/123拥有更多更细致的操作, 而不是所有的更新只能用同一个 API 完成.

操作名称会在 URL 的最后面,通常会是动词;是少数 URL 会出现动词的情况,

上面提到的模组名称/pso跟更新的操作 (agent/approved/rjected). 这些都是属于特别的资源原型(resource archetype). 关于 restful API 的四种 resource archetypes 可以在本文档的最下方的 Resource 里找到参考资料