写点什么

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

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

关注

评论

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

Python 设计模式:适配器模式

宇宙之一粟

设计模式 适配器模式 6月月更

Helix QAC更新至2022.1版本,将持续提供高标准合规覆盖率

龙智—DevSecOps解决方案

C语言 静态代码分析 Helix QAC 代码合规率 代码合规

解读2022年度敏捷教练行业现状报告

华为云开发者联盟

后端 开发 华为云

SAVE: 软件分析验证和测试平台

华为云开发者联盟

云计算 测试 后端 开发 软件分析

基于微信小程序的婚纱影楼小程序开发笔记

CC同学

小程序

火线沙龙第26期-多云安全专场

腾源会

为什么你的数据图谱分析图上只显示一个值?

清林情报分析师

数据分析 可视化 知识图谱 三元组 情报分析

活动报名 | MongoDB 5.0 时序存储特性介绍

MongoDB中文社区

mongodb

区块哈希竞猜游戏系统开发(dapp)

薇電13242772558

哈希值

脚本之美│VBS 入门交互实战

Windows Server 6月月更 VBS 脚本之美

理论+案例,带你掌握Angular依赖注入模式的应用

华为云开发者联盟

程序员 前端 华为云

墨天轮访谈 | IvorySQL王志斌—IvorySQL,一个基于PostgreSQL的兼容Oracle的开源数据库

墨天轮

数据库 oracle postgresql 开源

基于 ShardingSphere 的得物数据库中间件平台“彩虹桥”演进之路

SphereEx

数据库 中间件 ShardingSphere 实践

如何使用物联网低代码平台进行流程管理?

AIRIOT

低代码 物联网,

在宇宙的眼眸下,如何正确地关心东数西算?

脑极体

力扣每日一练之字符串Day6

京与旧铺

6月月更

如何通过7个步骤编写出色的在线用户手册

小炮

准备好迁移上云了?请收下这份迁移步骤清单

龙智—DevSecOps解决方案

迁移计划 迁移上云计划 迁移上云步骤 上云步骤清单 云迁移策略

应用实践 | Apache Doris 整合 Iceberg + Flink CDC 构建实时湖仓一体的联邦查询分析架构

SelectDB

数据库 flink Doris iceberg

直播分享| 腾讯云 MongoDB 智能诊断及性能优化实践

MongoDB中文社区

mongodb

如何利用数仓创建时序表

华为云开发者联盟

数据库 后端 华为云 时序表

vue快速学习、基础用法

开发微hkkf5566

盘点四种WiFi加密标准:WEP、WPA、WPA2、WPA3

wljslmz

wifi 6月月更 无线安全 wpa3 wep

如何轻松快速构建区块链应用?技术大牛带来一线技术实践分享

腾源会

好用的人事管理软件有哪些?人事管理系统软件排名!

优秀

企业管理软件 OA管理系统

游戏资产复用:更快找到所需游戏资产的新方法

龙智—DevSecOps解决方案

游戏开发 游戏资产 艾尔登法环 游戏资产复用

直播回顾 | 云原生混部系统 Koordinator 架构详解(附完整PPT)

阿里巴巴云原生

阿里云 架构 云原生 混部 Koordinator

八大误区,逐个击破(终篇):云难以扩展、定制性差,还会让管理员失去控制权?

龙智—DevSecOps解决方案

Atlassian 云版 版本选择 迁移上云

学C++还是学Java?做软件研发还需掌握哪些知识和技能?

dvlinker

Java c++ 数据库 网络知识 汇编代码

JDBC 在性能测试中的应用

阿里巴巴云原生

阿里云 云原生 JDBC 压测

混沌工程,了解一下

华为云开发者联盟

云计算 测试 后端 混沌工程 华为云

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