jsonkey命名规范_jsonapi
JSON API 规范
本⽂定义了⼀个标准的 JSON API规范，即⼀个应⽤于 Web 前后端 Ajax 数据交互规范，⽤以定义客户端如何获取与修改资源，以及服务器如何响应对应请求。
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 ⽂档作为资源操作介质。在⽂档顶层，依据资源类型分组。每个资源都通过⽂档下的唯⼀路径辨识。
相关的⽂档模块
##本⽂导航
[TOC]
规则约定
⽂档中的关键字， "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 依据RFC 2119
[RFC2119]规范解释。
⽂档结构
这⼀章节描述JSON API⽂档结构，通过媒体类型application/vnd.api+json标⽰。JSON API⽂档使⽤javascript 对象(JSON)
[RFC4627]定义。
尽管同种媒体类型⽤以请求和响应⽂档，但某些特性只适⽤于其中⼀种。差异在下⾯呈现。
Top Level
JSON 对象必须位于每个JSON API⽂档的根级。这个对象定义⽂档的“top level”。
⽂档的top level必须包含请求资源或者请求资源集合的实例 (即主要资源)。
主要资源应该以 资源类型 或者通⽤键 "data" 索引.
常见的APi Top Level主键说明
"code" - ⾃定义的资源响应状态编码或错误码，必须的键值，其值必须是整型数字，⽽且必须⼤于等于零。
"message"-可选，字符串，对 code 做进⼀步描述。当code的值 为 0 时，message 的值可选，当 code 的值⼤于 0 时，message 的值必填。
"data" - 主要资源的通⽤主键。可选值，⽤来存储返回的实体数据。如果 data存在，data-value可为常规数据类型或复合数据类型。如果其为复合数据类型，则为“值对”数据结构，或多维“值对”数据结构。
"id" - 特定问题的唯⼀标⽰符。资源对象的保留字。
"href" - 提供特定问题更多细节的URI。资源对象的保留字。
"status" - 请求响应的HTTP状态码，详情请看http 状态码描述。
"title" - 简短的，可读性⾼的问题总结。除了国际化本地化处理之外，不同场景下，相同的问题，值是不应该变动的。
"detail" - 针对该问题的⾼可读性解释。
"path" - 关联资源中相关属性的相对路径。在单资源或单类型资源中出现的问题，这个值才是合适的。"meta" - 资源的元信息，⽐如分页信息等
"links" - 扩展资源关联URLs的URL模板。资源对象的保留字
"linked" - 资源对象集合，按照类型分组，链接到主要资源或彼此(即链接资源)
资源表⽰
这⼀章节描述JSON API⽂档如何表⽰资源。适⽤于主要资源和链接资源。
个体资源表⽰
个体资源使⽤单⼀“资源对象”(如下描述)或者包含资源ID(如下描述)的字符串表⽰。
The following post is represented as a resource object:
下⾯的 posts 表⽰⼀个资源对象：
{
"status":200,
"code":0,
"data": {
"id": "1",
// ... attributes of this post
}
}
这个 posts ⽤ID简单地表⽰：
{
"code":0,
"posts": "1"
}
资源集合表⽰
任意数量资源的集合应该使⽤资源对象数组，或者IDs数组，或者⼀个简单的”集合对象“表⽰。
下⾯这个 posts 使⽤资源对象数组表⽰：
{
"code":0,
"posts": [{
"id": "1"
/
/ ... attributes of this post
}, {
"id": "2"
// ... attributes of this post
}]
}
这个posts使⽤IDs数组表⽰：
{
"code":0,
"posts": ["1", "2"]
}
这些comments使⽤单⼀集合对象表⽰：
{
"code":0,
"comments": {
"href": "example/comments/5,12,17,20",
"ids": [ "5", "12", "17", "20" ],
"type": "comments"
}
}
多资源对象
多个资源对象有相同的内部结构，不管他们表⽰主要资源还是链接资源。下⾯是⼀个可能出现在⽂档中的post(即"posts"类型的⼀个资源)：
{
"code":0,
"posts": {
"id": "1",
"title": "Rails is Omakase"
}
}
在上⾯这个例⼦中，post的资源对象⽐较简单：
//...
parsley{
"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应该由服务器指定，因此通常包含在响应⽂档中。
//...
[{
"id": "1",
"href": "example/comments/1",
"body": "Mmmmmakase"
}, {
"id": "2",
"href": "example/comments/2",
"body": "I prefer unagi"
}]
//...
服务器对特定URLGET请求，响应内容必须包含资源。
通常在响应⽂档的根层级声明URL 模板会更⾼效，⽽不是在每⼀个资源对象内声明独⽴的URLs。
资源关联
"links"键的值是⼀个表⽰链接资源的JSON对象，通过关联名索引。
举例来说，下⾯的post与⼀个author和⼀个comments集合相关联：//...
{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": "9",
"comments": [ "5", "12", "17", "20" ]
}
}
//...
单对象关联
单对象关联必须使⽤上⾯所述单资源形式的⼀种来表⽰。
举例来说，下⾯的post与⼀个author相关联，通过ID标⽰：
//...
{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": "17"
}
}
//...
下⾯是⼀个⽰例，链接的author⽤⼀个资源对象表⽰：
//...
{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": {
"href": "example/people/17",
"id": "17",
"type": "people"
}

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。