PATCH Support

JSON API服务器可以选择性支持，遵循JSON Patch规范[RFC6902]的HTTP PATCH请求。上面提到使用POST, PUT 和 DELETE进行的操作，JSON Patch都拥有等效操作。从这里开始，PATCH请求发出的JSON Patch操作，都被简单的称作“PATCH"操作。

PATCH请求必须声明Content-Type:application/json-patch+json头。

PATCH操作必须作为数组发送，以遵循JSON Patch规范。服务器可能会限制顶层数组类型，顺序和操作数量。

请求 URLs

每个PATCH请求的URL应该映射待更新的资源或关联。

PATCH操作内的每个"path"应该相对于请求URL。请求URL和PATCH操作的"path"是附加的，合并后获取特定资源，集合，属性，或者关联目标。

PATCH操作可以在API的根URL使用。此时，PATCH操作的"path"必须包含完整的资源URL。API表示的任意资源都可以进行常规的"fire hose"更新。如上所述，服务器可能会限制类型，排序和批量操作数量。

创建资源with PATCH

要创建资源，执行"add"操作， "path"指向对应资源集合的末尾 ("/-")。"value"必须包含一个资源对象。

比如，新photo通过如下请求创建：

PATCH /photos
Content-Type: application/json-patch+json
Accept: application/json

[
  { 
    "op": "add", 
    "path": "/-", 
    "value": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    }
  }
]

更新属性with PATCH

要更新属性，执行"replace" 操作，"path"值指定属性名。

例如，下面请求只更新/photos/1的src值。

PATCH /photos/1
Content-Type: application/json-patch+json

[
  {
  "op": "replace",
  "path": "/src",
  "value": "http://example.com/hamster.png"
 }
]

更新关联with PATCH

要更新关联，向对应的关联URL发出合适的PATCH操作即可。

服务器可能支持更高层级的更新，像资源的URL（甚至是API的根URL）。如上所述，请求URL和每个操作的"path"是附加的，合并后获得特定关联URL目标。

关联更新with PATCH

要更新单对象关联，对指向关联的URL和"path" 执行"replace"操作。

例如：下面请求更新article的author：

PATCH /article/1/links/author
Content-Type: application/json-patch+json

[
 {
  "op": "replace",
  "path": "/",
  "value": "1"
 }
]

要移除单对象关联，对关联执行remove操作。例如：

PATCH /article/1/links/author
Content-Type: application/json-patch+json

[
  { 
    "op": "remove", 
    "path": "/" 
  }
]

更新多对象关联 with PATCH

尽管在GET响应中，多对象关联以JSON数组形式表示，但是更新时更像是集合。

要添加元素到多对象关联，执行指向关联URL的"add" 请求。由于操作指向集合末尾， "path" 必须以"/-"结尾。

例如，考虑下面的GET请求：

GET /photos/1
Content-Type: application/vnd.api+json

{
  "links": {
    "comments": "http://example.com/comments/{comments}"
  },
  "photos": {
    "id": "1",
    "href": "http://example.com/photos/1",
    "title": "Hamster",
    "src": "images/hamster.png",
    "links": {
      "comments": [ "1", "5", "12", "17" ]
    }
  }
}

向PATCH请求执行add操作，即可将comment 30 转移到这个photo。

PATCH /photos/1/links/comments
Content-Type: application/json-patch+json

[
  { 
    "op": "add", 
    "path": "/-", 
    "value": "30"
  }
]

要移除多对象关联，对指向关联对象的URL执行"remove"操作。因为操作目标是元素集合，"path"必须以"/<id>"结尾。

比如，要移除photo的comment 5，执行"remove"操作：

PATCH /photos/1/links/comments
Content-Type: application/json-patch+json

[
  { 
    "op": "remove", 
    "path": "/5" 
  }
]

删除资源with PATCH

要删除资源，对指向资源的 URL 和"path"执行 "remove" 操作。

例如，photo 1 能使用下面请求删除：

PATCH /photos/1
Content-Type: application/json-patch+json
Accept: application/vnd.api+json

[
  { 
    "op": "remove",
    "path": "/"
  }
]

响应

204 No Content

若PATCH请求成功，客户端当前的属性保持最新，服务器必须响应204 No Content 状态码。

200 OK

如果服务器接受更新，但是在请求指定内容之外做了资源修改，必须响应200 OK以及更新的资源实例。

服务器必须指定Content-Type:application/json头。响应内容必须包含JSON对象数组，每个对象必须遵循JSON API媒体类型(application/vnd.api+json)。数组中的响应对象必须有序，并且对应请求文档操作。

例如，一个请求以分离操作，创建两个photos。

PATCH /photos
Content-Type: application/json-patch+json
Accept: application/json

[
  { 
    "op": "add", 
    "path": "/-", 
    "value": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    }
  },
  { 
    "op": "add", 
    "path": "/-", 
    "value": {
      "title": "Mustaches on a Stick",
      "src": "http://example.com/images/mustaches.png"
    }
  }
]

响应内容在数组中包含对应的JSON API文档。

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "photos": [{
      "id": "123",
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    }]
  }, {
    "photos": [{
      "id": "124",
      "title": "Mustaches on a Stick",
      "src": "http://example.com/images/mustaches.png"
    }]
  }
]

其它响应

当服务器执行PATCH请求时出现一个或多个问题，应该在响应中指定最合适的HTTP状态码。客户端依据HTTP规范解析错误。

服务器可以选择在第一个问题出现时，立刻终止PATCH 操作，或者继续执行，遇到多个问题。例如，服务器可能多属性更新，然后返回在一个响应里返回多个校验问题。

当服务器单个请求遇到多个问题，响应中应该指定最通用可行的HTTP错误码。例如，400 Bad Request适用于多个4xx errors，500 Internal Server Error适用于多个5xx errors。

服务器可能会返回与每个操作对应的错误对象。服务器需要指定Content-Type:application/json头，响应体必须包含JSON对象数组，每个对象必须遵循JSON API媒体类型 (application/vnd.api+json)。数组中的响应对象，必须是有序，且与请求文档中的操作相对应。每个响应对象应该仅包含error对象，当错误发生时，没有操作会完全成功。每个特定操作的错误码，应该在每个error对象 "status" 元素反映。

HTTP 缓存

服务器可能会使用遵循HTTP 1.1规范的HTTP 缓存头 (ETag, Last-Modified)。