创建,更新,删除资源
服务器可能支持资源获取,创建,更新和删除。
服务器允许单次请求,更新多个资源,如下所述。多个资源更新必须完全成功或者失败,不允许部分更新成功。
任何包含内容的请求,必须包含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的title
和text
属性。
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的title
和author
属性:
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规范处理这些错误信息。如下所述,错误细节可能会一并返回。