REST API 指定值选项的设计

Question

给定如下资源：

GET: /api/examples/1
{
  "id": 1,
  "direction": "North"
}

也支持POST, PUT，"direction"的可能值应该如何指定？

此外，是否有一种解决方案可以让消费者知道哪些值是可用的（如果这些值是上下文相关的）？例如如果这个例子变得更复杂：

GET: /api/examples/
{[
  {
    "id": 1,
    "startLocation": "Kentucky, USA",
    "direction": "North"
  }
  {
    "id": 2,
    "startLocation": "North Pole",
    "direction": "South"
  }
}]

（含糊不清的东西）：

"options": [
  {
    "value": "North",
    "validWhen": "startLocation !== `North Pole`"
  },
  {
    "value": "East",
    "validWhen": "true"
  },
  ...
]

是否有比从每个 example returns 当前有效选项链接的另一个资源更好的解决方案？如果不是，消费者如何知道更改 "startLocation" 会更改 "direction" 的有效值集？

Answer 1

为了扩展@Justas 在他的评论中所说的内容，如果我正确理解您的要求，您的资源可能类似于：

GET /examples/1
{
    "startLocation": "Kentucky, USA",
    ...
    "_links": {
        "travel-north": "/some/url",
        ...
    }
}

Answer 2

我认为您可能正在寻找的是 JSON-Schema。这允许您严格描述您的 JSON 文档中可用的选项，并且您可以 link 使用 describedBy link.

到文档

REST API 指定值选项的设计

REST API design for specifying value options

rest

api-design