AICon 北京站 Keynote 亮点揭秘,想了解 Agent 智能体来就对了! 了解详情
写点什么

GOTO Berlin: Web API 设计原则

  • 2013-10-22
  • 本文字数:1402 字

    阅读完需:约 5 分钟

在邮件列表和讨论区中有很多与 REST Web API 相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ 的首席顾问 Oliver Wolf GOTO Berlin 大会上开始自己的演讲“Web API 设计原则”时如是说。

不要考虑端点。 SOAP 有一个单独入口点的外观。相比之下 Web 有很多入口点,它们建立在关系上,彼此之间相互连接,并且以超媒体作为关键要素。为了不让你的 API 成为一个只有一种接入方式的黑洞,你应该使用超媒体控制按照对听众有意义的表现方式去链接你的资源。

** 不要在API中暴露领域模型。** 在很多模型中存在的一个问题便是它们仅包含数据,缺乏所有形式的行为,也就是所谓的贫血模型(anaemic model)。如果你暴露这样一个模型,那么最终将会成为 CRUD (创建、读取、更新和删除)和资源。这并不一定是一件坏事,有时你所需要的所有内容便是一个纯粹的 CRUD API。否则暴露一个 CRUD 模型的问题便是,使用这样一个 API 的客户端需要了解很多知识,清楚它能够对哪些资源执行什么操作,按照什么样的顺序执行等等这些内容。大量的逻辑需要编码在客户端中,使得客户端和服务器之间变得紧耦合。

** 目的明确之后再设计API。** 想想你的客户端想要做什么,如何做。有时这需要在清晰度和灵活性之间权衡,你需要多么简单清晰的 API,需要什么程度的灵活性。一种灵活但是也更加迫切的获取最有利可图的客户的方式是:

复制代码
GET /customers?sortBy=grossmargin&order=descending

相比之下,下面是一种声明意味更浓的暴露意图的方式,但是也缺乏灵活性:

复制代码
GET /most_profitable_customers

Oliver 提到这里需要注意的一点是,考虑一下客户端需要使用你的 API 做什么,它的意图应该是什么,并尽量让它完美契合这些需要。

** 不要过度使用GETPOST。** 这基本上意味着你不应该按照错误的方式使用它们,也不能违反 HTTP 规范。例如,你不应该使用 GET 或者 POST 删除资源。每个 HTTP 动词的产生都有各自的原因,它们之间是互补的,通过拥抱规范你得到的将会更多。使用动词传达目的,客户端想要做什么,它们期望从服务器得到哪些行为。

** 不要将错误码的选择限制为200500。** 使用完整范围的错误码,有 160 个错误码供你选择,所以几乎每一种类型的错误都有一个对应的错误码。使用正确的错误码是客户端能够合理处理错误的关键。一个常见的问题是,尽管发生了一个错误但是服务器依然返回 200,OK。在这种事情发生时假装所有事情运行良好显然不是一个很好的想法。

不要忽略缓存。 无论涉及到什么都会有缓存,它是 Web 的一个非常重要的部分。如果你不想使用缓存,那么通过添加合适的缓存头明确地关闭它。
一种比较好的控制缓存的方式是使用验证器,最好是 Etags。它们允许服务器端操作任意的数据,一个 Etag 仅仅是服务器生成并传入缓存的一个值,然后缓存会将其传回以询问服务器是否有更新的资源。

不需要版本。通常情况下,当资源发生变化的时候实际上它仅仅是展示发生了改变,而它依然是那个资源,应该使用同一个 URL,因此避免将 URL 版本化。相反的,应该有一个新版本的媒体类型,例如通过下面的方式添加版本 v2:

复制代码
Content-Type=application/vnd.company.v2+xml

不要对内容协商使用扩展。协商一种表现格式的正确方法是在消息头中使用 Accept 和 Content-Type。

2013 年的 GOTO Berlin 大会是 GOTO 大会首次在 Berlin 举行,本次大会有超过 400 位参会者和大约 80 位讲师。

查看英文原文 GOTO Berlin: DO’s and DON’Ts in a Web API

2013-10-22 03:473093
用户头像

发布了 321 篇内容, 共 127.1 次阅读, 收获喜欢 19 次。

关注

评论

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

ChatGPT 最好的替代品

图灵教育

机器学习 BERT ChatGPT

软件测试 | 元素定位方式与隐式等待

测吧(北京)科技有限公司

测试

软件测试 | App控件定位

测吧(北京)科技有限公司

测试

ChatGPT搜索风暴

OneFlow

人工智能 深度学习

软件测试 | adb命令的组成

测吧(北京)科技有限公司

测试

软件测试 | 触屏操作测试自动化

测吧(北京)科技有限公司

测试

基于 Flink 的小米数据集成实践

Apache Flink

大数据 flink 实时计算

谈JVM参数GC线程数ParallelGCThreads合理性设置

京东科技开发者

线程 JVM cpu GC线程 ParallelGCThreads

ChatGPT 最好的替代品

图灵社区

机器学习 Transformer BERT ChatGPT

软件测试 | App控件交互

测吧(北京)科技有限公司

测试

@所有人,OceanBase DevCon • 2023来啦!

OceanBase 数据库

数据库 oceanbase

拜占庭将军问题和 Raft 共识算法讲解

京东科技开发者

算法 分布式系统 拜占庭将军问题 raft共识算法 日志同步

软件测试 | App常见Bug解析

测吧(北京)科技有限公司

测试

实现“无感知”的网络运维,新华社融媒体流量分析平台的创新之路

智维数据

大数据 防火墙 数据可视化 智能运维 运维安全

软件测试 | 高级定位技巧

测吧(北京)科技有限公司

测试

Slurm集群调度策略详解(2)-回填调度

慕冰

Slurm 回填调度

设计模式第七讲-外观模式、适配器模式、模板方法模式详解

C++后台开发

设计模式 后端开发 Linux服务器开发 适配器模式 C++开发

3dmax的常用功能和使用方法

Finovy Cloud

3D渲染 3DMAX

软件测试 | 录制Appium测试用例

测吧(北京)科技有限公司

测试

怎么编写接口测试用例?

Liam

测试用例 如何编写测试 测试用例设计

OceanBase 4.0解读:兼顾高效与透明,我们对DDL的设计与思考

OceanBase 数据库

数据库 oceanbase

机器学习洞察 | 一文带你“讲透” JAX

亚马逊云科技 (Amazon Web Services)

中国人寿业务稳定性保障:“1+1+N” 落地生产全链路压测

TakinTalks稳定性社区

理论+实践,揭秘昇腾CANN算子开发

华为云开发者联盟

人工智能 AI 华为云 企业号 2 月 PK 榜 华为云开发者联盟

可靠、安全、稳定,开源高质量项目 | 亚马逊的开源文化

亚马逊云科技 (Amazon Web Services)

4道数学题,求解极狐GitLab CI 流水线|第2&3题:父子流水线 + 多项目流水线

极狐GitLab

ci DevOps pipeline 极狐GitLab 流水线

袋鼠云产品功能更新报告04期丨2023年首次,产品升级“狂飙”

袋鼠云数栈

【2.10-2.17】写作社区优秀技术博文一览

InfoQ写作社区官方

热门活动 优质创作周报

模块6 拆分电商系统为微服务

KING

软件测试 | Appium架构介绍与环境配置

测吧(北京)科技有限公司

测试

一卡通|多云流量监控支撑To C+To B,双向高效运维

智维数据

大数据 数据可视化 智能运维 运维安全

GOTO Berlin: Web API设计原则_SOA_Jan Stenberg_InfoQ精选文章