用于指定值选项的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链接的其他资源更好的解决方案，它返回当前有效选项？如果没有，消费者如何知道更改"startLocation"会更改"direction"的有效值集？

Answer 1

要扩展@Justas在评论中所说的内容，如果我正确理解您的要求，您的资源可能如下所示：

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

Answer 2

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