Jasper：API / 后向兼容性

ylbtech-Jasper：API / 后向兼容性

1.返回顶部

1、

后向兼容性

为了给客户提供创新的业务解决方案，Cisco Jasper 会定期扩展我们 API 框架的功能。我们会尽最大努力确保大多数 API 变更都可以后向兼容，使您无需在我们每次更改框架之后更新您的代码。后向兼容的变更包括：

• 向 API 服务添加 API 接口
• 向 API 接口添加方法
• 向方法添加 HTTP 绑定
• 向请求消息添加字段
• 向响应消息添加字段
• 向枚举添加值
• 添加仅输出资源字段

后向兼容的变更不会对符合最佳做法的应用程序产生影响。

编码指南

即使我们用上述某个后向兼容的变更更新了 API 框架，遵守下述编程指南的应用程序代码仍能继续正常运转。这些指南适用于使用 Control Center 的 REST API 和 SOAP API 的程序以及那些对来自 Control Center 推送 API 的消息进行解析的程序。

• 切勿对逻辑进行硬编码以匹配特定的参数顺序。
• 确保您的代码符合 HTTP 标准。该标准包括多个默认和可选参数，并且不断发展演变，经常出现新的标头和参数。
• 在进行字符串匹配之前，确保使用标记化来分隔标记。
• 在行的结尾处利用回车+换行符 (CRLF) 组合来提示没有更多要处理的标记。
• 根据数据类型对数据应用适当的转换。
• 始终在匹配逻辑中使用默认的“获取全部”以获取意外错误。

例如，假设您要解析 HTTP 标头中的 Content-Type 标记并基于该信息处理有效负载。一种方法是解析有效负载，查找与 content-type=application/x-www-form-urlencoded 精确匹配的字符串。不过，在将来的某个时候，Cisco Jasper 可能会决定使用可选参数 charset=UTF-8，这会将标记行更改为 content-type=application/x-www-form-urlencoded ; charset=UTF-8。HTTP 响应标头字符串中的这一变更会中断期望收到相同字符串的解析器代码。

更好的做法是分解标记，密切关注换行符和回车序列，放入错误捕获情景，等等。此特定标记在 HTTP 1.1 RFC2616(第 21 页)中定义为 <charset :token>，其中 charset 由 IANA 字符集注册表定义，Content-Type 是其中一个字符集。

要为 URL 编码形式的数据编写解析器，请参考万维网协会 (W3C) 的相关说明。

不可后向兼容的变更

尽管 Cisco Jasper 尽力确保大多数 API 变更都可以后向兼容，但有时冲突不可避免。不可后向兼容的变更包括：

• 删除或重命名服务、接口、字段、方法或枚举值
• 更改 HTTP 绑定
• 更改字段类型
• 更改资源名称格式
• 更改现有请求的可见行为
• 更改 HTTP 字义中的 URL 格式
• 向资源消息添加读取/写入字段

Cisco Jasper 会在不可后向兼容的变更生效前至少提前六个月向运营商发出通知。该通知将包括变更的具体信息，以及如何在不中断服务的情况下升级代码的指导说明。

API 版本

每个 API 函数都有一个版本号，用于标识 API 的结构和行为。Cisco Jasper 会在以下情况下递增此版本号：

• 函数收到不可后向兼容的变更，而且
• 前一版本的函数仍受支持。

如果 Cisco Jasper 进行后向兼容的函数变更，同时对前一版本的支持将会停止，则版本号保持不变。有关每种 API 类型的版本号，请参阅详细文档。

2、

2.返回顶部

 

3.返回顶部

 

4.返回顶部

 

5.返回顶部

 

 

6.返回顶部

 

作者：ylbtech 出处：http://ylbtech.cnblogs.com/ 本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。