HTTP API 设计格式

发布时间: 更新时间: 总字数:10229 阅读时间:21m 作者:IP:上海 网址

定义 HTTP API 设计格式,使 JSON 格式的 API 更加符合团队的需求。

扩展

  • 建议采用 OpenAPI 规范 定义 API
    • OpenAPI 规范(以前称为Swagger规范)是一种机器可读接口文件的规范,用于描述、生成、使用和可视化 RESTful Web 服务
    • httpbin.org 示例
    • Mocky 世界上最简单和最快的工具 Mock 的 API
    • YApi 是一个可本地部署的、打通前后端及 QA 的、可视化的接口管理平台

介绍

  • JSON API 是数据交互规范,用以定义客户端如何获取与修改资源,以及服务器如何响应对应请求。
  • JSON API 设计用来最小化请求的数量,以及客户端与服务器间传输的数据量。在高效实现的同时,无需牺牲可读性、灵活性和可发现性。
  • JSON API 需要使用 JSON API 媒体类型(application/vnd.api+json) 进行数据交互。
  • JSON API 服务器支持通过 GET 方法获取资源。而且必须独立实现 HTTP POST, PUT 和 DELETE 方法的请求响应,以支持资源的创建、更新和删除。
  • JSON API 服务器也可以选择性支持 HTTP PATCH 方法 [RFC5789]和 JSON Patch 格式 [RFC6902],进行资源修改。JSON Patch 支持是可行的,因为理论上来说,JSON API 通过单一 JSON 文档,反映域下的所有资源,并将 JSON 文档作为资源操作介质。在文档顶层,依据资源类型分组。每个资源都通过文档下的唯一路径辨识。

规则约定

文档中的关键字"MUST"、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”, and “OPTIONAL” 依据RFC2119规范解释。

文档结构

这一章节描述 JSON API 文档结构,通过媒体类型application/vnd.api+json标示。JSON API 文档使用 javascript 对象(JSON)[RFC4627]定义。

尽管同种媒体类型用以请求和响应文档,但某些特性只适用于其中一种。差异在下面呈现。

Top Level

JSON 对象必须位于每个 JSON API 文档的根级。这个对象定义文档的“top level”。

文档的 top level 必须包含请求资源或者请求资源集合的实例 (即主要资源)。

主要资源应该以资源类型或者通用键"data"索引.

  • "meta": 资源的元信息,比如分页.
  • "links": 扩展资源关联 URLs 的 URL 模板.
  • "linked": 资源对象集合,按照类型分组,链接到主要资源或彼此(即链接资源)

资源表示

这一章节描述 JSON API 文档如何表示资源。适用于主要资源和链接资源。

个体资源表示

个体资源使用单一“资源对象”(如下描述)或者包含资源 ID(如下描述)的字符串表示。

The following post is represented as a resource object: 下面的 post 表示一个资源对象:

javascript
{
  "posts": {
    "id": "1",
    // ... attributes of this post
  }
}

这个 post 用 ID 简单地表示:

javascript
{
  "posts": "1"
}

资源集合表示

任意数量资源的集合应该使用资源对象数组,或者 IDs 数组,或者一个简单的”集合对象“表示。

下面这个 post 使用资源对象数组表示:

javascript
{
  "posts": [{
    "id": "1"
    // ... attributes of this post
  }, {
    "id": "2"
    // ... attributes of this post
  }]
}

这个 posts 使用 IDs 数组表示:

javascript
{
  "posts": ["1", "2"]
}

这些 comments 使用单一集合对象表示:

javascript
{
  "comments": {
    "href": "http://example.com/comments/5,12,17,20",
    "ids": [ "5", "12", "17", "20" ],
    "type": "comments"
  }
}

多资源对象

多个资源对象有相同的内部结构,不管他们表示主要资源还是链接资源。

下面是一个可能出现在文档中的 post(即”posts"类型的一个资源):

javascript
{
  "posts": {
    "id": "1",
    "title": "Rails is Omakase"
  }
}

在上面这个例子中,post 的资源对象比较简单:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase"
  }
//...

这一章节专注于资源对象,在完整 JSON API 文档上下文环境之外。

资源属性

资源对象有四个保留字:

  • "id"
  • "type"
  • "href"
  • "links"

资源对象中的其它键表示一个“属性”。一个属性值可以是任何 JSON 值。

资源 IDs

每一个资源对象应该有一个唯一标示符,或者 ID。如下所示,IDs 可由服务器或者客户端指定,and SHOULD be unique for a resource when scoped by its type. ID 应该使用 "id"键表示,值必须是字符串,且只包含字母,数字,连字符和下划线。

URL 模板可以使用 IDs 来获取关联资源,如下所示。

在特殊场景下,客户端与服务器之间的唯一标识符信息非必要,JSON API 允许缺省 IDs。

资源类型

每个资源对象的类型通常由它所在的上下文环境决定。如上面讨论,资源对象在文档中通过类型索引。

每一个资源对象可能包含 "type" 键来显示指定类型。

当资源的类型在文档中未声明时,"type"键不可缺省。

资源 URLs

每一个资源的 URL 可能使用"href"键声明。资源 URLs 应该由服务器指定,因此通常包含在响应文档中。

javascript
//...
  [{
    "id": "1",
    "href": "http://example.com/comments/1",
    "body": "Mmmmmakase"
  }, {
    "id": "2",
    "href": "http://example.com/comments/2",
    "body": "I prefer unagi"
  }]
//...

服务器对特定 URLGET请求,响应内容必须包含资源。

通常在响应文档的根层级声明 URL 模板会更高效,而不是在每一个资源对象内声明独立的 URLs。

资源关联

"links"键的值是一个表示链接资源的 JSON 对象,通过关联名索引。

举例来说,下面的 post 与一个author和一个comments集合相关联:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "5", "12", "17", "20" ]
    }
  }
//...
单对象关联

单对象关联必须使用上面所述单资源形式的一种来表示。

举例来说,下面的 post 与一个 author 相关联,通过 ID 标示:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "17"
    }
  }
//...

下面是一个示例,链接的 author 用一个资源对象表示:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": {
        "href": "http://example.com/people/17",
        "id": "17",
        "type": "people"
      }
    }
  }
//...

空白的单对象关联应该用null值表示。举例来说,下面的 post 没有关联 author:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": null
    }
  }
//...
多对象关联

多对象关联必须使用上述资源集合形式的一种来表示。

举例来说,下面的 post 与多个 comments 关联,通过 IDs 标示:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "comments": [ "5", "12", "17", "20" ]
    }
  }
//...

这是一个使用集合对象链接的 comments 数组:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "comments": {
        "href": "http://example.com/comments/5,12,17,20",
        "ids": [ "5", "12", "17", "20" ],
        "type": "comments"
      }
    }
  }
//...

空白的多对象关联应该使用空数组表示。举例来说,下面的 post 没有 comments:

javascript
//...
  {
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "comments": []
    }
  }
//...

集合对象

“集合对象”包含一个或多个元素:

  • "ids" - 关联资源的 IDs 数组。
  • "type" - 资源类型
  • "href" - 关联资源的 URL(适用于响应文档)。

提供包含href属性集合对象的服务器,必须响应特定 URL GET 请求,响应内容包含资源对象集合的关联资源。

URL 模板

顶层的 "links" 对象可用来声明 URL 模板,从而依据资源对象类型获取最终 URLs。

举例说明:

javascript
{
  "links": {
    "posts.comments": "http://example.com/comments?posts={posts.id}"
  },
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase"
  }, {
    "id": "2",
    "title": "The Parley Letter"
  }]
}

在这个示例中,请求http://example.com/comments?posts=1 将会得到"Rails is Omakase"的 comments,请求http://example.com/comments?posts=2 将会得到 "The Parley Letter"的 comments.

下面是另外一个示例:

javascript
{
  "links": {
    "posts.comments": "http://example.com/comments/{posts.comments}"
  },
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "comments": [ "1", "2", "3", "4" ]
    }
  }]
}

在这个示例中,处理每个 post"links"区块内的特定数组,以扩展posts.comments变量。URI 模板规范 [RFC6570]声明默认处理方式,使用%编码(即encodeURIComponent() javascript 原生方法)编码每一个元素,然后用逗号连接。在这个示例中,请求http://example.com/comments/1,2,3,4 ,将会获取一个comments列表。

顶层 "links"对象具有以下行为:

  • 每个键使用点分隔路径,指向重复的关联。路径以特定资源类型名开头,遍历相关的资源。举例来 说,"posts.comments"指向每个"posts"对象的"comments"关联.
  • 每个键的值作为 URL 模板处理。
  • 每个 path 指向的资源,就像是使用实际指定的非 URL 值扩展 URL 模板形成的关联。

这是另外一个使用单对象关联的示例:

javascript
{
  "links": {
    "posts.author": "http://example.com/people/{posts.author}"
  },
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "12"
    }
  }, {
    "id": "2",
    "title": "The Parley Letter",
    "links": {
      "author": "12"
    }
  }, {
    "id": "3",
    "title": "Dependency Injection is Not a Virtue",
    "links": {
      "author": "12"
    }
  }]
}

这个实例中,三个 posts 指向 author 的 URL 都为http://example.com/people/12.

顶层 URL 模板允许指定关联作为 IDs,但是不要求客户端硬编码来获取 URLs 的信息.

注意:为防止冲突,单独资源对象的links对象优先级高于顶层的links对象。

复合文档

为减少 HTTP 请求,响应需要返回所请求的主要资源,同时可以选择性的包含链接资源。这样的响应称作“复合文档”。

在复合文档中,链接资源必须作为资源对象,包含在文档顶层"linked"对象中,依据类型,组合到不同数组中。

每个关联的类型,可以在资源层级,或顶层"links"对象层级,使用"type"键指定。能够辅助客户端查询链接资源对象。

javascript
{
  "links": {
    "posts.author": {
      "href": "http://example.com/people/{posts.author}",
      "type": "people"
    },
    "posts.comments": {
      "href": "http://example.com/comments/{posts.comments}",
      "type": "comments"
    }
  },
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "1", "2", "3" ]
    }}, {
    "id": "2",
    "title": "The Parley Letter",
    "links": {
      "author": "9",
      "comments": [ "4", "5" ]
   }}, {
    "id": "1",
    "title": "Dependency Injection is Not a Virtue",
    "links": {
      "author": "9",
      "comments": [ "6" ]
    }
  }],
  "linked": {
    "people": [{
      "id": "9",
      "name": "@d2h"
    }],
    "comments": [{
      "id": "1",
      "body": "Mmmmmakase"
    }, {
      "id": "2",
      "body": "I prefer unagi"
    }, {
      "id": "3",
      "body": "What's Omakase?"
    }, {
      "id": "4",
      "body": "Parley is a discussion, especially one between enemies"
    }, {
      "id": "5",
      "body": "The parsley letter"
    }, {
      "id": "6",
      "body": "Dependency Injection is Not a Vice"
    }]
  }
}

这种处理方式,保证随每个响应返回每个文档的单例,即使当相同的文档被多次引用时(这个实例中三个 posts 的 author)。沿着这种方式,如果主要文档链接到另外的主要或链接文档,在"linked"对象中也不应该重复。

URLs

关联文档

确定 API 的 URL 结构时,考虑把所有的资源放置于单一“关联文档"是有用的,在关联文档中,每个资源都被分配唯一路径。在文档顶层,资源依据类型分组。在分类资源集合中,单独资源通过 ID 索引。其属性和 links,依据资源对象结构,唯一分配。

关联文档的概念,用于为资源及资源关系确定合适的 URLs。重要的一点,出于不同目标和限制,用于传输资源的不同文档中,关联文档的结构有轻微差异。例如,在关联文档中的资源集当做集合处理,因为元素必须通过 ID 访问,在传输文档中的资源集当做数组处理,因为顺序比较重要。

资源集合 URLs

资源集合的 URL 应该依据资源类型确定。

例如,”photos”类型的资源集合应该使用这种 URL:

text
/photos

单独资源 URLs

资源集应该作为集合,依据资源 ID 索引。单独资源的 URL 通过为集合 URL 添加资源 ID 生成。

例如,ID 为"1"的 photo 使用这种 URL:

text
/photos/1

多个单独资源的 URL 通过为集合 URL 添加逗号分隔的资源 IDs 列表生成。

例如,IDs 为"1", "2", "3"的 photos 使用这种 URL:

text
/photos/1,2,3

替代性 URLs

资源的替代性 URLs 可以选择在响应中指定,或者通过"href"或 URL 模板指定。

关联 URLs

添加/links/<relationship-name>到资源 URL 后面,即得到访问特定资源的关联资源 URL。相对路径与资源对象内部结构保持一致。

例如,photo 的 comments 链接集使用这种 URL:

text
/photos/1/links/comments

A photo’s reference to an individual linked photographer will have the URL: photo 的 photographer 链接使用这种 URL:

text
/photos/1/links/photographer

服务器使用单独资源响应单对象关联,使用资源集合响应多对象关联。

资源获取

资源,或者资源集合,通过向 URL 发出GET请求获取。

响应内容可以使用如下所示的特点,进一步细化。

过滤

服务器可以选择性支持,依据指定标准进行资源过滤。

通过向资源集合的基准 URL 添加过滤参数,来支持资源过滤。

例如,下面是请求与特定 post 关联的所有 comments:

text
GET /comments?posts=1

使用这种方案,单一请求可以使用多过滤器:

text
GET /comments?posts=1&author=12

这种规范仅支持基于严格匹配的资源过滤。API 允许使用的额外过滤器应该在它的侧写中指定。 (见 Extending)

内链资源

服务器可以选择性支持,返回包含主要资源和链接资源对象的复合文档。

默认情况下,后端返回链接主要资源的资源对象。

后端也可以基于请求中include的参数,支持自定义链接资源。参数应该指定一个或者多个,相对于主要资源的相对路径。如果指定参数值,只有请求的链接资源,应该随主要资源返回。

例如,comments 可以通过 post 请求:

text
GET /posts/1?include=comments

为请求链接到其他资源的资源,需要指定每个关联的点分隔路径。

text
GET /posts/1?include=comments.author

注意:对comments.author的请求,在响应中不应该自动包含comments资源(尽管 comments 也需要显式查询,以获取 authors 响应请求)。

多链接资源可以使用点分隔列表请求:

text
GET /posts/1?include=author,comments,comments.author

稀疏字段

服务器可以选择性支持,仅返回资源对象的指定字段。

后端可以基于fields参数,以支持返回主要资源的指定字段。

text
GET /people?fields=id,name,age

后端可以基于fields[TYPE]参数,以支持返回任意类型资源的特定字段。

text
GET /posts?include=author&fields[posts]=id,title&fields[people]=id,name

若没有指定类型对象的字段,或者后端不支持field或fields[TYPE]参数,后端会默认返回资源对象的所有字段。

后端可以选择总是返回有限的,未指定的字段集,例如id or href.

注意: fields 和 fields[TYPE]不能混合使用。如果使用后者,那么必须与主要资源类型同时使用。

排序

服务器可以选择性支持,基于特定标准对资源集合排序。

后端基于sort参数,以支持主要资源类型的排序。

text
GET /people?sort=age

后端支持多字段排序,将sort值设置为点分隔值即可。排序标准用以获取特定顺序。

text
GET /people?sort=age,name

默认排序方式为升序排序。任意排序字段,使用-前缀指定降序排序。

text
GET /posts?sort=-created,title

上面的示例应该首先返回最新的 posts。同一天创建的 posts,依据 title 值进行字母升序排列。

后端基于sort[TYPE]参数,以支持对任意资源类型排序。

text
GET /posts?include=author&sort[posts]=-created,title&sort[people]=name

如果没有指定排序方式,或者后端不支持sort和sort[TYPE],后端将会返回使用重复算法排序的资源对象。换言之,资源应该总是以相同顺序返回,即使排序规则没有指定。

注意:sort和sort[TYPE]不能混用。如果使用后者,必须与主要资源一同使用。

创建,更新,删除资源

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

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

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

创建资源

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

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

创建单独资源

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

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

javascript
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 通过如下请求创建:

javascript
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](http://tools.ietf.org/html/draft-ietf- httpbis-p2-semantics-22#section-6.3)规范,响应成功的资源创建请求。

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

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

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

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

javascript
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。

例如:

javascript
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请求。请求必须包含一个顶层资源对象。

例如:

javascript
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"元素。

例如:

javascript
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属性。

javascript
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属性:

javascript
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请求,即可添加单对象关联。

例如:

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

{
  "people": "12"
}

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

text
DELETE /articles/1/links/author
更新多关联对象

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

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

javascript
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请求,即可添加多对象关联。

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

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

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

text
DELETE /articles/1/links/tags/1

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

text
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请求即可删除单个资源。

text
DELETE /photos/1

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

text
DELETE /photos/1,2,3

响应

204 No Content

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

其它响应

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

Errors

错误对象是特殊化的资源对象,可能在响应中一并返回,用以提供执行操作遭遇问题的额外信息。在在 JSON API 文档顶层,"errors"对应值即为错误对象集合,此时文档不应该包含其它顶层资源。

错误对象可能有以下元素:

  • "id" - 特定问题的唯一标示符。
  • "href" - 提供特定问题更多细节的 URI。
  • "status" - 适用于这个问题的 HTTP 状态码,使用字符串表示。
  • "code" - 应用特定的错误码,以字符串表示。
  • "title" - 简短的,可读性高的问题总结。除了国际化本地化处理之外,不同场景下,相同的问题,值是不应该变动的。
  • "detail" - 针对该问题的高可读性解释。
  • "links" - 可以在请求文档中取消应用的关联资源。
  • "path" - 关联资源中相关属性的相对路径。在单资源或单类型资源中出现的问题,这个值才是合适的。

额外的元素可以在错误对象中指定。

实现接口可以选择使用其它的 errors 媒体类型。

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 通过如下请求创建:

javascript
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值。

javascript
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:

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

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

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

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

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

更新多对象关联 with PATCH

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

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

例如,考虑下面的GET请求:

javascript
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。

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

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

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

比如,要移除 photo 的 comment 5,执行"remove"操作:

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

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

删除资源 with PATCH

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

例如,photo 1 能使用下面请求删除:

javascript
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。

javascript
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 文档。

javascript
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)。

Header 头规范

标准头

yaml
Content-Type: application/vnd.api+json
Accept: application/vnd.{团队名称}.{版本号: v1, v2, ...}+json

说明:

  • application/vnd.api+json : JSON API 在 IANA 机构完成注册的 MIME 类型
  • application/vnd.{团队名称}.{版本号: v1, v2, ...}+json 服务器接收类型

认证头

text
Authorization: Bearer {用户token}

其他需要注意的内容(建议)

yaml
User-Agent: {Agent info}
User-Agent: Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>

错误描述

javascript
{
   "message": "Validation Failed",
   "errors": [
     {
       "resource": "Issue",
       "field": "title",
       "code": "missing_field"
     }
   ]
 }

所有错误包括下面信息

  • missing: 说明某个字段的值代表的资源不存在
  • invalid: 某个字段的值非法,接口文档中会提供相应的信息
  • missing_field: 缺失某个必须的字段
  • already_exist: 发送的资源中的某个字段的值和服务器中已有的某个资源冲突,常见于某些值全局唯一的字段,比如 @ 用的用户名(这个错误我有纠结,因为其实有 409 状态码可以表示,但是在修改某个资源时,很一般显然请求中不止是一种错误,如果是 409 的话,多种错误的场景就不合适了)

参考

  1. https://github.com/justjavac/json-api-zh_CN