写点什么

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:473103
用户头像

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

关注

评论

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

InfoQ 极客传媒 15 周年庆征文|手把手教你使用Python实现一键抠图,照片换背景|so easy!

迷彩

Python AI 前端 6月月更 InfoQ极客传媒15周年庆

谁说Redis不能存大key

华为云开发者联盟

数据库 华为云

一、Kafka安装

星期35

【资源分享】综合性的导航网站

小炮

vue指令-5

小恺

6月月更

CREMB Pro 后台子管理员 403 问题分析

CRMEB

身为程序猿——谷歌浏览器的这些骚操作你真的会吗

孤寒者

6月月更 浏览器操作 小技巧 程序猿必会

亚马逊云科技向你发出召唤——游戏开发者,集合!

亚马逊云科技 (Amazon Web Services)

react.js edge postcss

【MySQL字符串数据类型优化】char和varchar的区别

写代码两年半

数据库 sql 6月月更

10个常见触发IO瓶颈的高频业务场景

华为云开发者联盟

数据库 sql 索引 华为云 数据清理

尽一份孝心,为家人做一个老人防摔报警系统

华为云开发者联盟

IoT 华为云 防摔倒报警系统

不止于观测|阿里云可观测技术峰会正式上线

阿里巴巴中间件

阿里云 云原生 可观测技术峰会

线程池

急需上岸的小谢

6月月更

君可归烈士寻亲系统开发实战

乌龟哥哥

6月月更

每日一题——leecode59( 螺旋矩阵 II)

武师叔

6月月更

大数据生态安全框架的实现原理与最佳实践(上篇)

明哥的IT随笔

大数据 hadoop hive 数据安全

华为云零代码开发图片压缩工具

乌龟哥哥

6月月更

直播预告 | 在阿里云 ESSD 云盘上部署 PolarDB for PostgreSQL 集群

阿里云数据库开源

数据库 postgresql 阿里云 开源

干货合集│最好用的 python 库都在这

Python 有趣的技术知识 6月月更

从源码解析flutter_redux 的精准局部刷新

岛上码农

flutter ios 安卓开发 跨平台应用 6月月更

【Spring 学习笔记(八)】Spring IoC/DI注解开发 之 原始注解开发

倔强的牛角

Java spring Java EE 6月月更

【愚公系列】2022年06月 面向对象设计原则(四)-依赖倒置原则

愚公搬代码

6月月更

什么是集群?为什么要使用集群架构?

Finovy Cloud

集群架构 云渲染 GPU服务器

企业内部Wiki,你建立了么?

小炮

音频 3A 处理实践,让你的应用更「动听」

融云 RongCloud

跟我学Python图像处理丨5种图像阈值化处理及算法对比

华为云开发者联盟

Python 人工智能 华为云

在线沙龙 | 开源小秀场——数据库技术应用实践

SelectDB

数据库 技术分享 apache doris 沙龙

react框架学习之深入研究【王道react】

恒山其若陋兮

6月月更

数据库每日一题---第7天:订单最多的客户

知心宝贝

数据库 程序员 前端 后端 6月月更

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