写点什么

HTTP API 可演进性最佳实践

  • 2012-02-05
  • 本文字数:1830 字

    阅读完需:约 6 分钟

正如标题所示,Benjamin Carlyle 试图在《Best Practices For HTTP API Evolvability》一文中为围绕 HTTP API 构建的系统的设计定义原则和实践,这些系统是可扩展的,并且能一直进化下去。他先指出了 REST(一种架构风格)和 HTTP API(通过 HTTP 暴露的编程接口)之间的区别。

HTTP API 是针对一个特定服务的面向开发者的接口,也被称为 RESTful 服务契约面向资源架构 URI Space

我说 REST 和 HTTP API 紧密相关是因为大多数 HTTP API 并不严格遵守统一接口约束,严格说来统一接口约束要求接口是“标准的”[…]

文章开头他标识出了 API 设计中的不同元素,这些元素决定了 API 后续的进化。通常来说,API 进化涉及到了设计客户端与服务器的兼容性;特别是 API 的向后和向前兼容变更。 变更频率按增序排列依次是:

  1. API 中用到的方法的通用语义,包含异常条件和其他元数据
  2. API 中用到的媒体类型的通用语义,包含全部 Schema 信息
  3. 构成 API 的 URI 集合,包含 API 中用到的每个通用方法和媒体类型的特定语义

API 进化中改变最少的就是方法的语义。文中描述的最佳实践是识别出向前和向后兼容的变化,运用 Postel 法则让服务与客户端以一种更能容忍的方式进行进化。他建议尽可能地使用 HTTP 错误码来传达兼容性问题。

最佳实践 3:新方法名应该选择那些不会和任何已有方法发生向前兼容的名字。例如,如果要处理的方法必须正确理解(必须理解语义)方法的新特性,那么应该选择一个新的方法名。

最佳实践 4:服务应该忽略它们不理解的标头或组件。代理应该不加修改地传递这些标头,或者是无法理解的组件。

[…]

最佳实践 7:在某个数字范围内为新状态分配一个状态码,这个范围可以粗粒度地标识已存在的条件。

[…]

最佳实践 9:如果新状态是一个已知状态(除了 400 Bad Request 或 500 Internal Server Error)的子集,可以向响应头添加信息来细化已知状态的含义,而不是分配一个新的状态码。

他指出了一个重要的区别,即客户端与服务器交互中媒体类型的对称本质。

[…] 与客户端和服务器之间非对称的方法和状态不同,媒体类型通常能用作请求或响应的负载,即适用于两个方向。为此本节中我们不讨论客户端与服务器,而是讲发送端与接收端。

…这构成了与媒体类型相关的最佳实践的基础

[…]

最佳实践 11:只有当验证逻辑是为与文档发送方相同版本或后续版本的 API 编写的情况下,才可能出现不符合最佳实践 10 的文档验证。

最佳实践 12:在不违反媒体类型设计目标的前提下,如果能向现有媒体类型的 Schema 中添加新信息,那么就添加吧。

他提倡使用 Content-Types 和 Accept 标头来管理发送端与接收端之间的兼容性。

HTTP API 习惯于做出向后不兼容的媒体类型 Schema 变更。新客户端请求或者提供了 Schema 中带有向后不兼容变更的新媒体类型。老的客户端继续请求或提供旧的媒体类型。直到所有重要的相关实现都升级到最新的媒体类型集之前,客户端与服务器端都应该要支持旧的媒体类型。

他认为对资源的修改,尤其是 URI 的修改都是服务器应该关心的事;如果客户端是设计成由超媒体约束驱动的话,一般这些修改都不应该引入兼容性问题。他提倡使用 Cookies 将客户端请求路由到合适的服务实例 / 服务器。

在使用多种通用方法时,我们不再处理通用的方法或媒体类型,而是和带有特定语义的特定 URL 打交道。[…] 在考虑如下服务契约时,我倾向于采用以服务器为中心的视角:

  • GET /invoice/{invoice-id},返回媒体类型 application/invoice+xml,内容是 invoice-id 指定的发货单
  • GET /invoice/{invoice-id}/paid,返回媒体类型 text/plain( xsd:bool 语法),内容是 invoice-id 指定的发货单的支付状态
  • PUT /invoice/{invoice-id}/paid,接受媒体类型 text/plain( xsd:bool 语法),设置 invoice-id 指定的发货单的支付状态

此外,他还提出了一些客户端的最佳实践,以便客户端能应对服务器 URI 的转变(transition)和进化。

最佳实践 19:在升级时,服务应该通过 Cookies 追踪哪些客户端应该连接到旧的服务器,哪些应该连接到新的服务器,或者也可以使用类似的机制。

最佳实践 20:即使不是在响应 HEAD 或 GET 请求,客户端也应该遵从服务器发回的重定向状态响应 [说明: RFC2616 ]

最佳实践 21:重新设计 URL 时,确保新的 URL 拥有和旧 URL 一样的语义,并将旧 URL 重定向到新的 URL 上。

本文中提供了一些基本原理,让 HTTP API 系统能随着时间不断进化。请务必阅读 Benjamin Carlyle 的完整原文以便对这一主题能有更深入的理解。

查看英文原文: Best Practices For HTTP API Evolvability

2012-02-05 09:163653
用户头像

发布了 135 篇内容, 共 62.7 次阅读, 收获喜欢 43 次。

关注

评论

发布
暂无评论
发现更多内容

微信公众平台-渠道二维码开发

Geek_247dae

优雅地停止Spring Boot应用

韩斌

未来赚钱的行业大预测

ES_her0

28天写作

无人机蜂群

冠冠

记忆这件“小事”「Day 7」

道伟

心理学 28天写作

(28DW-S8-Day7) 比特币原始文献略读

mtfelix

比特币 区块链 白皮书 28天写作 工作量证明

从萧何进入咸阳丞相府到数字化时代的决策

数列科技杨德华

28天写作

产品经理第五周:如何绘制流程图?

克比

简单脚本监控SSL证书,并到期提醒续签

运维研习社

如何探索自己的职业价值观,让工作更有动力

一笑

28天写作

前端170面试题+答案学习整理(良心制作)

我是哪吒

程序员 面试 大前端 28天写作 2月春节不断更

产品迭代最有力的工具:每周产品讨论会

boshi

产品策略 七日更

Elasticsearch 相关度评分

escray

elastic 七日更 28天写作 死磕Elasticsearch 60天通过Elastic认证考试 2月春节不断更

分布式应用监控与链路追踪:SkyWalking

xcbeyond

微服务 监控 Skywalking 调用链 28天写作

翻译:《实用的 Python 编程》02_07_Objects

codists

Python

Linux常见IO分析工具

运维研习社

医者,智也:智慧医院破茧时,翻开转型新一页

脑极体

第五周作业:用例流程图

克比

收音机焊接

aaaaa

这道 Hard 到底难在哪里?大概是难在考察的全是违反“人性直觉”的内容吧 ...

宫水三叶的刷题日记

面试 LeetCode 数据结构与算法

Nginx中常见header配置及修改

运维研习社

nginx Linux

分页问题-Offset-based Pagination和Cursor-based Pagination

诸葛小猿

分页 Offset-based Pagination Cursor-based Pagination

云主机配置微信公众号后台全记录

小jack

【LeetCode】猜字谜Java题解

Albert

算法 LeetCode 28天写作 2月春节不断更

28天瞎写的第二百四十五天:怎么样开始练习冥想?

树上

冥想 28天写作 正念

万绿丛中一点红——雷斯多夫效应

Justin

心理学 交互设计 28天写作 游戏设计

Docker安装

Sakura

Docker

Java中的String类型到底占用多大的内存空间?

冰河

Java 性能优化 string 高并发 内存空间

开源镜像仓库Harbor的镜像安全

运维研习社

Docker 安全 Harbor CI/CD

攀爬天梯的手机厂商,能从LG的滑落中学到什么?

脑极体

元宵佳节快乐哦

Nydia

HTTP API可演进性最佳实践_REST_Dilip Krishnan_InfoQ精选文章