如果我有一个 RESTful API 的基本 URL，有没有办法确定它提供了哪些资源？

Question

我有一个 RESTful API 的基本 URL。我有一个它提供的一些资源类型的列表。喜欢：

GET http://www.baseURL.com:8180/fruits

会产生类似的结果：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <FruitList xmlns="http://www.baseURL.com/Fruits">
  <Fruit>
    <Identity createdTimeStamp="2011-05-13T09:45:16.611-05:00" lastUpdatedTimeStamp="2012-11-19T03:24:19.310-06:00">
        <FruitName>Apple</FruitName>
    </Identity>
  </Fruit>
  <Fruit>
    <Identity createdTimeStamp="2011-05-13T09:45:17.241-05:00" lastUpdatedTimeStamp="2012-11-19T03:24:20.431-06:00">
      <FruitName>Banana</FruitName>
    </Identity>
  </Fruit>
  <Fruit>
    <Identity createdTimeStamp="2011-05-13T09:45:19.445-05:00" lastUpdatedTimeStamp="2012-11-19T03:24:21.281-06:00">
      <FruitName>Orange</FruitName>
    </Identity>
</Fruit>
</FruitList>

如果我不知道这个 API 有“水果”作为资源，我是否可以通过某种通用的 GET 命令来解决这个问题？

Answer 1

所有通信都需要一些高级知识，包括 RESTful API。如果我说“你好”而你只说克林贡语，你可能会认为我在侮辱你。 RESTful API 所需的预设知识包括：

• 入口点（URL）
• 了解接口以及如何有效地使用它（即 HTTP 方法和返回码 - 请参阅 REST API - why use PUT DELETE POST GET? 了解更多信息）
• 可以合理预期可以使用哪些表示格式
• 了解这些格式的语义

这些应该被记录，以便客户作者可以使用它们。因此，尽可能重用现有规范而不是发明新规范是有意义的。这样做意味着现有客户可以理解您的大部分或全部 API，甚至无需查看任何文档。这样就可以将新网站添加到 Internet，而无需浏览器供应商返回并更新其浏览器以访问新网站。

例如在 HTML 中：

entry point = http://www.example.com/
hypertext formats expected = HTML, XHTML, SVG, etc.

现代浏览器知道每一个的语义，所以当它在 HTML 响应中遇到文本时

<link rel="stylesheet" href="/style.css">

它会知道 LINK 元素代表一个超媒体路径，并且资源的关系是“样式表”关系的关系，它理解这具有一定的效果（即重新设置主要响应的呈现方式）。

您的 API 应该在其基本 URL http://www.baseURL.com:8180/ 中包含一组指向其提供的资源的超媒体链接 <a href="/fruits">Fruits</a>，任何理解 HTML 的客户端都可以访问这些链接。如果您想为这些链接添加含义，则需要提供关系。已经存在 list of pre-defined link relations 但如果这些都不适合您，您可以寻找在其他公共本体中定义的合适关系，或者使用您控制的命名空间中的 URI 定义您自己的关系。建议使用提供人类可读文档的可取消引用的 HTTP URL。例如：

rel="http://www.baseURL.com:8180/documentation/#FruitList"

所以，直接回答你的问题，

如果我不知道这个 API 有“水果”作为资源，我是否可以通过某种通用 GET 命令来解决这个问题？

您的客户端需要获取 API 的入口 URL，查看为每个链接提供的关系，并知道这意味着什么，因为它是在某处预定义的，并且客户端知道 FruitList 对用户意味着什么。

Answer 2

对此没有标准。即使您收到了回复，您也无法知道回复的含义意味着什么。