关于 RESTful API 的几个问题以及为什么很少实施一些最佳实践

Question

在大多数关于 RESTful 的教程、文档、文章等中，我遇到了一些相同的观点，但我很少看到这些“是什么让 RESTful 实现”的观点。

例如，我读过很多遍：

• 内容类型

  使用 HTTP 标头

  Accept: application/json, text/plain 
  

  网址中的扩展名

  Not RESTful, URLs are not the place for Content-Type
  

我从未遇到过实现此功能的 API。我曾经使用过的每个 API 都要求我将 XML 或 JSON 附加到 URL 的末尾。他们做错了吗？

• 版本控制

  版本媒体类型

  应用程序/vnd.something.v1+json

  自定义标题

  X-API-版本：1

  网址中的版本

  /v1/资源 不是 RESTful，通过将版本放在您创建单独资源的 URL 中

如果您需要引入非向后兼容的功能，确定创建单独的资源是正确的做法吗？

再一次，在我使用过的所有 API 版本中，它们在 URL 中使用 v1、v2（例如 google、imgur 等）

如果不实现这些点，我的 API 会不会被视为 RESTful？

非常感谢澄清这些观点。

Answer 1

1) 使用接受标头或使用特定格式的 URL 在 RESTful 系统中均有效。你引用的文章是错误的。

2) 说v1/resource 不是 RESTful 也是不正确的。您无法查看 URI 并对其 RESTful 做出结论。如果您尝试增量演进系统，在 URL 的根目录添加 v1 可能不是一件好事。实际上，它声明了一个全新的 URL 空间并废弃了旧的。这是相当激烈的。 RESTFul 系统尝试并支持对系统进行增量和渐进式更改。所以/resource/v2实际上更符合这个目标。

这里发生的不幸现象是，许多正在学习 REST 的开发人员发现，绝大多数声称使用 REST 的系统实际上并不符合 REST 的约束。因此，他们很快就热衷于告诉每个人什么是 RESTful，什么不是 RESTful。这些人中的许多人还没有完全理解这些限制，最终编造了一些不存在的新限制。 “RESTFul URL”谬误是一个经典。 “POST 必须创建资源”是另一个常见的。

我对任何学习 REST 的人的指导是，如果有人告诉你某些东西不是 RESTful，你要问他们它违反了什么约束以及忽略该约束的实际影响是什么。如果他们无法回答，请礼貌地忽略他们。

Answer 2

REST 的真正定义显然在 Roy Fielding 在 2002 年编写的doctoral dissertation 中。所有自称为 RESTful 的 API 是否都遵循 Fielding 指定的准则？答案是不。 REST 的定义已经被一些人淡化为任何不使用 SOAP 的东西。我不太担心什么是 RESTful，而更多地担心什么是好的实践。在请求的标头中指定内容类型是一种很好的做法。对 API 进行版本控制也是一个很好的做法。 Apigee 的人提供了有关 API 最佳实践信息的一个很好的资源，因为他们在这方面有很多经验。在RESTful API Design 上查看他们的网络研讨会，他们会询问您是实用主义者还是 RESTafarian。