在 REST 中为您的状态表示引用 JSON 模式的最佳实践是什么？

Question

假设我有一个 REST 端点，允许客户 POST 一个新的 Article。它的 URL 是 http://api.example.com/articles. I also have an end point that they can GET a previously posted Article. Its URL is http://api.example.com/articles/{articleId}

一篇文章的状态表示是这样的。

{
    "title": "Some title",
    "body": "Article body"
}

所以原始 POST 请求：-

POST http://api.example.com/articles HTTP/1.1
Content-Type: application/vnd.example.com.article+json
Host: api.example.com
Content-Length: 76

{
    "title": "Some title",
    "body": "Article body"
}

原始 GET 请求：-

GET http://api.example.com/articles/dfgh HTTP/1.1
Accept: application/vnd.example.com.article+json
Host: api.example.com

现在我花时间提供了一个JSON Schema schema to describe my article state representation. Hosted at http://spec.api.example.com/article.json

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "body": {
            "type": "string"
        }
    },
    "required": [
        "title",
        "body"
    ]
}

针对此类 GET 和 POST 请求向客户提供此文档的最佳做法是什么？

Answer 1

记录如何提出请求的最好方法是使用某种超媒体格式来表达它。我个人的偏好是 JSON Hyper-Schema，并且由于您已经在使用 JSON Schema，所以它很适合。

创建文章的 link 看起来像这样。

{
  "rel": "create",
  "href": "/articles",
  "method": "post",
  "schema": { "$ref": "http://spec.api.example.com/article.json" }
}

因此，下一步是确定如何公开此 link 描述对象 (LDO)。答案取决于您的 API 流程，但这里有几个常见选项。

API的入口点

GET http://api.example.com/

HTTP/1.1 200 OK
Link: <http://spec.api.example.com/index.json>; rel=describedby

...

GET http://spec.api.example.com/index.json

HTTP/1.1 200 OK

{
  "links": [
    {
      "rel": "create",
      "href": "/articles",
      "method": "post",
      "schema": { "$ref": "http://spec.api.example.com/article.json" }
    }
  ]
}

文章列表资源

GET http://api.example.com/articles

HTTP/1.1 200 OK
Link: <http://spec.api.example.com/articles.json>; rel=describedby

[
  {
    "title": "Some title",
    "body": "Article body"
  },
  {
    "title": "Another title",
    "body": "Article body"
  }
]

GET http://spec.api.example.com/articles.json

HTTP/1.1 200 OK

{
  "type": "array",
  "items": { "$ref": "http://spec.api.example.com/article.json" },
  "links": [
    {
      "rel": "create",
      "href": "/articles",
      "method": "post",
      "schema": { "$ref": "http://spec.api.example.com/article.json" }
    }
  ]
}

Answer 2

REST API 的另一种表示法是 RAML. It uses YAML 用于描述您的资源，request/response 主体是使用 JSON 模式定义的。有一些工具能够从 RAML 描述生成文档，但是使用您的 API 的抽象定义不限于文档（其他工具支持伪造服务器生成等）

在 REST 中为您的状态表示引用 JSON 模式的最佳实践是什么？

What is the best practice for referencing JSON Schema for your state representations in REST?

rest

json

jsonschema