我如何询问 REST 服务器它拥有哪些资源？

Question

假设我在 https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/ 模拟了一个 REST 服务器，它有两个端点，spaceballs/raspberry 和 spaceballs/technician。这些端点将使用包含来自 Spaceballs 的引号的正文响应 HTTP GET 请求，例如

curl -X GET "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/raspberry"
Only one man would dare give me the raspberry!

和

curl -X GET "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/technician"
We got the bleeps, sweeps and the creeps!

所以一切都很好，但是如果我不知道这两个端点，只知道 RESTful 服务器的 URL 怎么办？我怎么能问那个（在这种情况下，模拟的）服务器它有什么资源？

Answer 1

作为客户端，您不必知道这两个端点！这是 REST 的基本原则之一，您的资源应该是可发现的。

了解 https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/ 的端点，您的用户应该能够使用超媒体在 API 中导航。实际上，这意味着您的入口点 returns link 指向其他相关资源。因此你应该有这样的东西；

GET https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/

{
  "self": {
    "type": "link.list",
    "uri": "/",
    "href": "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/"
  },
  "links": [
    {
      "rel": "film",
      "type": "link.list",
      "href": "https://https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs"
    }
  ]
}

上面的响应告诉客户端当前的 URI 是一个 link 的列表，并且有一个 link（称为 "film"）指向 [=23= 处的另一个资源] 并且该资源也是 link 的列表。使用此信息，客户端可以调用 API;

GET https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs

{
  "self": {
    "type": "link.list",
    "uri": "/spaceballs",
    "href": "https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs"
  },
  "links": [
    {
      "rel": "quote",
      "type": "film.quote",
      "href": "https://https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/raspberry"
    },
    {
      "rel": "quote",
      "type": "film.quote",
      "href": "https://https://50281ac6-ece9-42d3-9590-8e3325f50bd9.mock.pstmn.io/spaceballs/technician"
    }
  ]
}

您现在已经使用超媒体来描述您的应用程序的状态，并且正在着手编写 REST API！这是非常非常重要的一点。诸如此类的描述性 link 不是 "nice to have" - 它们是必需的。如果您的 API 不能像这样工作，那它就不是 REST。

我如何询问 REST 服务器它拥有哪些资源？

How can I ask a REST server what resources it has?

api

rest

endpoint