返回首页 用 JSON 构建 API 的标准指南
FAQ

创建,更新,删除资源

服务器可能支持资源获取,创建,更新和删除。

服务器允许单次请求,更新多个资源,如下所述。多个资源更新必须完全成功或者失败,不允许部分更新成功。

任何包含内容的请求,必须包含Content-Type:application/vnd.api+json请求头。

创建资源

支持资源创建的服务器,必须支持创建单独的资源,可以选择性支持一次请求,创建多个资源。

向表示待创建资源所属资源集的URL,发出POST请求,创建一个或多个资源。

创建单独资源

创建单独资源的请求必须包含单一主要资源对象。

例如,新photo可以通过如下请求创建:

POST /photos
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "photos": {
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }
}

创建多个资源

创建多个资源的请求必须包含主要主要资源集合。

例如,多个photos通过如下请求创建:

POST /photos
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

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

响应

201 状态码

服务器依据HTTP semantics规范,响应成功的资源创建请求。

当一个或多个资源创建成功,服务器返回201 Created状态码。

响应必须包含Location头,用以标示请求创建所有资源的位置。

如果创建了单个资源,且资源对象包含href键,Location URL必须匹配href值。

响应必须含有一个文档,用以存储所创建的主要资源。如果缺失,客户端则判定资源创建时,传输的文档未经修改。

HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json

{
  "photos": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "href": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000",
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }
}

其它响应

服务器可能使用其它HTTP错误状态码反映错误。客户端必须依据HTTP规范处理这些错误信息。如下所述,错误细节可能会一并返回。

客户端生成 IDs

请求创建一个或多个资源时,服务器可能接受客户端生成IDs。IDs必须使用"id"键来指定,其值必须正确生成,且为格式化的UUID

例如:

POST /photos
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "photos": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }
}

更新资源

支持资源更新的服务器必须支持单个资源的更新,可以选择性的支持单次请求更新多个资源。

向表示单独资源或多个单独资源的URL发出PUT请求,即可进行资源更新。

更新单独资源

为更新单独资源,向表示资源的URL发出PUT请求。请求必须包含一个顶层资源对象。

例如:

PUT /articles/1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "articles": {
    "id": "1",
    "title": "To TDD or Not"
  }
}

更新多个资源

向表示多个单独资源(不是全部的资源集合)的URL发出PUT请求,即可更新多个资源。请求必须包含顶层资源对象集合,且每个资源具有“id"元素。

例如:

PUT /articles/1,2
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "articles": [{
    "id": "1",
    "title": "To TDD or Not"
  }, {
    "id": "2",
    "title": "LOL Engineering"
  }]
}

更新属性

要更新资源的一个或多个属性,主要资源对象应该只包括待更新的属性。资源对象缺省的属性将不会更新。

例如,下面的PUT请求,仅会更新article的titletext属性。

PUT /articles/1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "articles": {
    "id": "1",
    "title": "To TDD or Not",
    "text": "TLDR; It's complicated... but check your test coverage regardless."
  }
}

更新关联

更新单对象关联

单对象关联更新,可以在PUT请求资源对象中包含links键,从而与其它属性一起更新。

例如,下面的PUT请求将会更新article的titleauthor属性:

PUT /articles/1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "articles": {
    "title": "Rails is a Melting Pot",
    "links": {
      "author": "1"
    }
  }
}

若要移除单对象关联,指定null作为值即可。

另外,单对象关联也可以通过它的关联URL访问。

向关联URL发出带有主要资源的POST请求,即可添加单对象关联。

例如:

POST /articles/1/links/author
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "people": "12"
}

向关联URL发出DELETE请求,即可删除单对象关联。例如:

DELETE /articles/1/links/author

更新多关联对象

更新多对象关联,可以在PUT请求中资源对象包含links键,从而与其它属性一起更新。

例如,下面PUT请求完全替换article的tags

PUT /articles/1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "articles": {
    "id": "1",
    "title": "Rails is a Melting Pot",
    "links": {
      "tags": ["2", "3"]
    }
  }
}

若要移除多对象关联,指定空数组[]为值即可。

在分布式系统中,完全替换一个数据集合并不总是合适。替换方案是允许单独的添加或移除关联。

为促进细化访问,多对象关联也可以通过关联URL访问。

向关联URL发出带有主要资源的POST请求,即可添加多对象关联。

POST /articles/1/links/comments
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "comments": ["1", "2"]
}

向关联URL发出DELETE请求,即可删除多对象对象关联。例如:

DELETE /articles/1/links/tags/1

向关联URL发出DELETE请求,即可删除多个多对象对象关联。例如:

DELETE /articles/1/links/tags/1,2

响应

204 No Content

如果更新成功,且客户端属性保持最新,服务器必须返回204 No Content状态码。适用于PUT请求,以及仅调整links,不涉及其它属性的POST, DELETE请求。

200 OK

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

其它响应

服务器使用其它HTTP错误状态码反映错误。客户端必须依据HTTP规范处理这些错误信息。如下所述,错误细节可能会一并返回。

资源删除

向资源URL发出DELETE请求即可删除单个资源。

DELETE /photos/1

服务器可以选择性的支持,在一个请求里删除多个资源。

DELETE /photos/1,2,3

响应

204 No Content

如果删除请求成功,服务器必须返回204 No Content 状态码。

其它响应

服务器使用其它HTTP错误状态码反映错误。客户端必须依据HTTP规范处理这些错误信息。如下所述,错误细节可能会一并返回。

上一篇: 资源获取 下一篇: Errors