REST API 与 Web API

Question

我是构建 HTTP API 的初学者，我似乎对 REST API 和 Web API 之间的区别感到困惑。我在网上阅读了更多关于它的信息，似乎混淆了。我猜菲尔丁和这个链接有同样的问题http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

我在工作中构建了一个 HTTP API，以为我构建了一个 REST API，因为我在任何地方都在构建 Web/HTTP API 并将其称为 REST。

当我发现一个遵循 HATEOAS 原则的 API 是一个 Github REST API https://api.github.com。我尝试在 Github (GET https://api.github.com/users/vvs14) 上使用它作为我的用户名，它根据 HATEOAS 原则返回所有相关链接。

它是最接近 REST 规范的真实世界 API 之一，恕我直言。虽然我不明白哪个 URI 支持对它的什么操作，以及如果我是它的消费者，或者如果我托管 API，如何告诉消费者如何在任何 REST API 的情况下找到它？

一个不错的博客是https://www.e4developer.com/2018/02/16/hateoas-simple-explanation/。

大多数博客中都给出了所有其他示例，只是告诉使用 JSON 作为 REST API，将所有内容作为资源作为 REST API，并使用 HTTP 动词进行 CRUD 操作作为 REST API。我不认为这些是真的。

在我的工作中，我使用 Sendgrid 的 Web API 向客户发送电子邮件，他们称之为 Web API，而不是 REST，我认为这很正确。

谁能用例子说明这两者之间的区别？

如果 Github API 是 REST API 的正确示例，我们如何知道哪个 URI 支持哪些操作，因为这里没有提到媒体类型？

Answer 1

唯一可以告诉您它支持什么的资源是资源本身。资源为您提供的有关其他资源支持的任何信息纯粹是建议性的。找出答案的唯一真正方法是尝试并处理成功/失败。这是因为接受的请求可能每分钟都在变化（例如删除）。

如果您的 API 可以在网络浏览器中导航并且可以提交表单（客户端除了起始 URL 和 HTML 格式之外对您的 API 一无所知）并且假设 text/html 是您 API 的可协商表示，那么它是RESTful。即使它不能在浏览器中导航，它也可以是 RESTful 的，但这更难演示。

Answer 2

你是对的，有很多混乱。专家们通常将“真正的”REST API 称为 HATEOAS 或超媒体驱动的 API，以避免这种混淆。大多数确实称自己为 REST api 的 API 通常不是。

因此，在与其他工程师讨论 REST api 时，首先澄清每个人认为 REST 而不是 REST 是有帮助的。他们不是不知道的坏工程师，“REST”这个词有它自己的生命，我会说 HATEOAS 可能更多的是一种小众技能。

我同意 Nicholas Shank 的回答，即在许多情况下，要弄清楚例如 DELETE 是否有效，一般要做的事情是实际发出 DELETE，然后看看它是否有效。

但这并不总是有帮助，因为许多构建 API 的人会希望在它无论如何都不起作用时不显示“删除”按钮。

那么告诉客户DELETE 可用的合理方式是什么？ HTTP 标准实际上确实有一个 Allow 标头，您可以使用它来找出在给定端点上工作的方法。要了解这些是什么，您可以发出OPTIONS 请求。并非每个框架都支持开箱即用，但这是一种合法的方式。

另一种提前告知客户的方法是将此信息嵌入您正在访问的资源中。举几个例子：

1. link hints 是一个互联网标准草案，它可以在各种不同的地方给出这些提示，例如 HAL、HTTP 链接头或其他。它基本上建议了此信息的通用格式。
2. 如果您使用 OpenAPI 之类的东西，您可以在您的 API 规范中添加哪些方法可以工作，哪些方法不能工作。这适用于您知道 DELETE 根本不会起作用的情况，但在不同用户可能具有不同访问级别的情况下，它对您没有帮助，有些人可以使用 DELETE 而其他人可以不。
3. 您可以将这些信息嵌入到您自己的格式中，将其表示为一组权限，可能是您的应用程序可以理解的 JSON 格式，以解释是否可以执行某些操作。
4. 一些 HATEAOS 格式明确嵌入了有关可以通过操作执行何种操作的信息。一个很好的例子是SIREN 格式。 HAL 本身没有这个。

最终，一个好的 HATEAOS 格式不仅会向他人返回有关资源和关系的信息，还会给出一组可以采取的潜在行动。 是 HATEAOS 的大多数 REST API 往往不这样做，但 HTML 是最好的例子。如果没有链接、按钮或表单来执行某项操作，则用户无法发现该操作。

嵌入在 HAL 中的链接提示示例

{
  "_links": {
    "self": {
      "href": "/orders/523",
      "hints": {
        "allow": ["GET", "DELETE"],
      }
    }
  }
}

SIREN 示例

 {
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 523, 
  },
  "actions": [
    {
      "name": "delete-order",
      "title": "Delete Order",
      "method": "DELETE",
      "href": "/orders/523",
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "/orders/523" },
  ]
}

OPTIONS 响应

HTTP/1.1 200 OK
Allow: GET, DELETE