Question

我是使用REST API的新手，但我看到许多暴露REST API的系统不提供将返回的消息的架构（结构）。因此，我们无法确定如何准确地解析响应。例如，今天的API调用可能会返回一组特定的字段，有些日子后，他们可能希望在响应中添加另一个字段，这可能会破坏我的解析器。所以，如果我要解析特定电话的回复信息，我该怎样才能以正确的方式做到？公开这些API的系统如何在内部处理调用？

Answer 1

这就是发明版本化的原因，如果发生重大变化，负责任的提供商将拥有不同的版本号。

几乎所有使用的库都可能发生这种情况，而不仅仅是REST API。

通常惯例是让您的版本编号采用Major.minor.patch格式（请参阅http://semver.org/）。任何破坏向后兼容性的东西都应该有一个主版本号。当然，并非所有的维护者都遵循这一点，完全遵循它，如果您使用API的提供商在这方面做得很差，那么您就无法做多。

您可以做的是确保您正在实施和管理所有库的依赖项版本控制，包括您的API，知道您希望支持哪个版本使用基于explict版本的调用而不是

http://example.com/api/customers/1234

使用

http://example.com/api/v3.0/customers/1234

并跟踪项目的依赖关系，同时跟踪提供商的更新文档，看看这是否会对您产生影响

关于API处于无模式格式，而新字段可能不会产生问题，删除现有字段或更改演示文稿，逻辑等将以难以调试的方式破坏您的代码，这些更改可能很微妙。

一旦提供者我使用更改字段全部小写但没有通知我，我的应用程序期望该字段的唯一值，但在一些罕见的情况下得到类似的值，我花了几天时间来弄清楚在哪里和发生了什么事，

Answer 2

许多REST服务使用JSON作为编码数据的基本格式。客户端应该简单地忽略他们在JSON响应中不知道的属性，从而允许服务器随着时间推移其输出（假设服务器不重命名或删除属性）。 REST服务版本控制本身就是一个完整的讨论（尝试搜索它）。

所以简而言之 - 新字段不应该弄乱你的解析器，它应该简单地忽略它们。

Answer 3

嗯，大多数好人都这样做！例如，参见OpenStack REST API。此外，请注意，返回的响应是针对特定版本的API，即，如果您使用 API（比如说）：

/api/v1.0/interfaces/interface

并且，您可能会得到一些字段：

{ "name : "eth0",  "ip" : "10.1.1.1" }

现在，API可能会发展，并且可能会有1.1版本，它会添加一些字段（保留向后兼容性）。即，/api/v1.1/interfaces/interface可能会返回：

{ "name : "eth0",  "ip" : "10.1.1.1" , "mtu" : 1500 }

或2.0具有完全不同的结构，打破向后兼容性：

GET /api/v2.0/interfaces/interface 
...
{ "interface" : { "name : "eth0",  "ip" : "10.1.1.1" , "mtu" : 1500 }}

再次，所有这些都必须有详细记录！

并且，使用API的代码必须知道他们感兴趣的版本，并相应地解析响应。

响应的格式，BTW取决于您提出的请求类型，例如，如果您将Accept-encoding设置为JSON（Accept: application/json），则返回的响应必须在JSON中 - 所以你知道要使用哪个解析器。

HTH

其余API的模式

3 个答案: