尝试查看哪种模型最适合api
(低更新,但对象结构可能会经常更改,高读取应用程序(
我有这样的资源
- EPIC (ID,名称,描述,开始日期,关闭日期,状态,状态,状态故事(
- 故事(ID,名称,描述,开始日期,关闭日期,状态,任务(
- 任务(ID,名称,描述,开始日期,解决日期,分辨率(
如果我需要支持这些更新,
- 更新 Epic 名称或描述或日期或状态
- 更新故事名称或描述或日期或状态
- 更新任务名称或描述或日期或状态
哪个是有道理的?
PATCH
with application/merge-patch+json
RFC 7396
资源应匹配目标对象结构
- 史诗/{id}
- 史诗/{id1}/story/{id2} ..等等
PATCH
with application/json
- 我倾向于选择此,因为无需严格强制执行RFC 7396
和灵活性来更新更新规则。
您要更新的自定义规则(但是从技术上讲 - 我可以发送需要更新类似于application/merge-patch+json
的资源属性(
- 史诗/{id}
- 史诗/{id1}/story/{id2} ..等等
PUT
with application/json
资源应与所有字段匹配并创建新对象并替换(或仅在补丁中像patch一样更新(
- 史诗/{id}
- 史诗/{id1}/story/{id2} ..等等
PUT
with application/json
或作弊,只有像补丁一样更新,但使用put
- 史诗/{id}
- 史诗/{id1}/story/{id2} ..等等
从静止的角度来看,要牢记的重要一件事是统一接口 - 您拥有带有application/json
表示的一些资源。我可以GET
您的表示形式,并使用我最喜欢的工具进行本地编辑。
如果我想提出应该更改资源以匹配我的表示形式,我们将从HTTP协议中选择适当的方法。换句话说,HTTP中的方法都是"通过网络运输本文档"的一部分。领域。(参考:吉姆·韦伯(Jim Webber(,2011年(。
如此现实,支持"所有人"是确保最宽的通用客户端可用于与您的资源交互的方法。
PUT /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/json
完全合理的起点;它具有几个优点 - 语义是有能力的,因此客户知道可以重复一个丢失的请求,而HTTP put包含了重要用例的语义,例如我们接受您的表示形式,因为您可以减少网络压力。
当表示比更改大得多时,可能是一个不幸的选择。
PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: ????
这是处理对大型表示的微小更改的完全合理方法。您会放弃一些PUT的优势 - 丢失的消息现在更加复杂。
PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/json
毫无用处。application/json
不是补丁文档格式 - 您无法知道如果没有某种带外协议,则该代表正在描述哪些更改。
PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/vnd.example.patch+json
PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/prs.example.patch+json
这是"休息"做之前的方法;您定义自定义媒体类型,并记录语义,然后将实现媒体类型的任何客户端使用。供应商树和虚荣树可用。+json
位是结构化语法名称后缀,它为无法识别基本子类型的消费者提供了一个结构提示。
PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/json-patch+json
PATCH /31E772D3-0157-4B52-8243-75EEAB946E65
Content-Type: application/merge-patch+json
也很棒的选择,因为这两种类型已在RFC 6902和RFC 7936中进行了标准化;您有更好的机会让客户已经知道这些类型。
一个了解HTTP补丁的客户端大概还会知道如何使用选项方法来发现服务器准备处理的方法和补丁文档格式。
OPTIONS /31E772D3-0157-4B52-8243-75EEAB946E65
HTTP/1.1 204 No Content
Allow: OPTIONS, GET, HEAD, PUT, PATCH
Accept-Patch: application/prs.example.patch+json, application/json-patch+json, application/merge-patch+json