GOTO Berlin: Web API设计原则
在邮件列表和讨论区中有很多与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做什么,它的意图应该是什么,并尽量让它完美契合这些需要。
不要过度使用GET和POST。这基本上意味着你不应该按照错误的方式使用它们,也不能违反HTTP规范。例如,你不应该使用GET或者POST删除资源。每个HTTP动词的产生都有各自的原因,它们之间是互补的,通过拥抱规范你得到的将会更多。使用动词传达目的,客户端想要做什么,它们期望从服务器得到哪些行为。
不要将错误码的选择限制为200和500。使用完整范围的错误码,有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
GOTO Berlin: Web API设计原则的更多相关文章
- Web API设计
Web API设计经验与总结 在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建. 通过Http协议的形式来. ...
- RESTful API设计原则与规范
RESTful API设计原则与规范 一.背景与基础概念 2 二.RESTful API应遵循的原则 3 1.协议(Protocol) 3 2.域名(ROOT URL) 3 3.版本(Versioni ...
- javascript的api设计原则
前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来.很难做到 ...
- 我所理解的RESTful Web API [设计篇]
<我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...
- Atitit. Api 设计 原则 ---归一化
Atitit. Api 设计 原则 ---归一化 1.1. 叫做归一化1 1.2. 归一化的实例:一切对象都可以序列化/toString 通过接口实现1 1.3. 泛文件概念.2 1.4. 游戏行业 ...
- Web API 设计摘要
近期读了一本微电子书 Brian Mulloy 所著<Web API Design>感觉颇多收获,特对其内容做了个整理摘要以便回想其观点精华以指导日常工作中的设计思路. 本文主要讲述 We ...
- API设计原则
译序 Qt的设计水准在业界很有口碑,一致.易于掌握和强大的API是Qt最著名的优点之一.此文既是Qt官网上的API设计指导准则,也是Qt在API设计上的实践总结.虽然Qt用的是C++,但其中设计原则和 ...
- Web API设计方法论
英文原文:A Web API Design Methodology 为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定 ...
- Web API设计方法论--比较完整的web api 开发过程
为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护 ...
随机推荐
- 各大IT技术博客排行榜
cnblogs 积分排名前3000名 http://www.cnblogs.com/ 左侧有推荐博客排行 cppblog http://www.cppblog.com/AllBloggers.aspx ...
- U-BOOT分析之:环境变量
(环境如下:U-BOOT S3C2440 LINUX) 记录自己的学习过程,如果分析有问题,请帮忙指正. 最近在研究U-BOOT的代码,其中的环境变量个人觉得用处非常大,所以重点学习和分析一下. ...
- 华为荣耀6 H60-L02/L12(联通版)救砖包【适用于无限重启】
本帖最后由 HOT米粒 于 2014-11-16 20:43 编辑 华为荣耀6 H60-L02/L12(联通版)救砖包[适用于无限重启]说明: 1.本工具包用于华为荣耀6 H60-L02(联通版): ...
- 【面试题】M
一面: 1.介绍实习项目: 2.计算二叉树叶子节点的数量: 3.排序算法有哪些,手写快排: 4.长度为100的数组,值为1~100,乱序,将其中一个值改为0,找出被更改的值以及位置: 5.输入数值0~ ...
- 朴素贝叶斯算法下的情感分析——C#编程实现
这篇文章做了什么 朴素贝叶斯算法是机器学习中非常重要的分类算法,用途十分广泛,如垃圾邮件处理等.而情感分析(Sentiment Analysis)是自然语言处理(Natural Language Pr ...
- [NOIP2016]愤怒的小鸟 D2 T3 状压DP
[NOIP2016]愤怒的小鸟 D2 T3 Description Kiana最近沉迷于一款神奇的游戏无法自拔. 简单来说,这款游戏是在一个平面上进行的. 有一架弹弓位于(0,0)处,每次Kiana可 ...
- 【翻译svg教程 】svg 的坐标系统
http://tutorials.jenkov.com/svg/svg-coordinate-system.html svg的坐标系统(和大多数计算机绘图的坐标系统)和数学中绘图系统有点不一样 数学/ ...
- 第三章 一个简单的机器学习例子让你了解DeepLab的语言风格
MINST是由Yann LeCun等人建立并维护的手写数字识别数据库.该数据库总共包含60000个训练样本和10000个测试样本.其中每个样本的大小是一张28*28的手写数字图片.数字包括从0~9总共 ...
- 【尺取】POJ 3320
POJ 3320 Jessica's Reading Problem 题意:一本书P页,第i页有ai知识点,问你至少从某一处开始连续要翻多少页才能复习完所有的知识点,不能跨页翻. 思路:<挑战程 ...
- UVA103 dp基础题,DAG模型
1.UVA103 嵌套n维空间 DAG模型记忆化搜索,或者 最长上升子序列. 2.dp[i]=max( dp[j]+1),(第i个小于第j个) (1) //DAG模型记忆化搜索 #include< ...