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

Posted 2023-02-16

【中文标题】关于 RESTful API 的几个问题以及为啥很少实施一些最佳实践

【英文标题】：A few questions about RESTful APIs and why some of the best-practices are rarely implemented关于 RESTful API 的几个问题以及为什么很少实施一些最佳实践

【发布时间】：2012-04-25 10:38:12

【问题描述】：

在大多数关于 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？

非常感谢澄清这些观点。

【问题讨论】：

小心假设现有的将自己标记为“RESTful”的 API 确实是 RESTful。我发现了解什么是 REST 的最简单来源是 Rest in Practice 书。遗憾的是，REST 一词已被用来描述任何通过 HTTP 实现的 API。

【参考方案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，你要问他们它违反了什么约束以及忽略该约束的实际影响是什么。如果他们无法回答，请礼貌地忽略他们。

【讨论】：

感谢您的回答和澄清要点。事实上，你说得对，大多数自称为 RESTful 的 API 根本不是。

【参考方案2】：

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

【讨论】：

感谢您的回答。 apigee 链接非常有趣！就像网络研讨会一样！

@Flukey 如果您观看 Brian Mulloy 稍后关于超媒体的网络研讨会，他接着说使用术语实用 REST 是错误的。