Web API 设计摘要

标签: web api 设计 | 发表时间:2014-06-25 03:20 | 作者:mindfloating
出处:http://blog.csdn.net

最近读了一本微电子书 Brian Mulloy 所著《Web API Design》感觉颇多收获,特对其内容做了个整理摘要以便回顾其观点精华以指导日常工作中的设计思路。


本文主要讲述 Web API 设计,追求一种更务实的 REST 风格。 正如作者所说 REST 是一种架构风格,而非严格的标准,没必要在形式定义上去做过多真论,到底什么才是真正的 REST? 设计的目的是为了表达某样东西是如何使用的,那么 API 设计的成功与否是由开发人员是否能够快速上手并用的愉快。

下面讲述了 Web API 设计的 13 个要点。


本条是关于 URL 设计的,使用名词而非动词,让 URL 保持简单和符合直觉。
这条是针对资源型 URL 设计而言,为什么?请看下一条。



用名词表达来领域概念,可以极大的减少 URL(API)的需求量。
使用 HTTP 协议方法动作来操作领域概念集。
通过分离概念和行为极大简化了 API 设计,让 URL 中只体现概念而非行为。



/elements/elementId 的二级 URL 形式,第一级表达元素集合,第二级表达集合中某个具体元素 id,因此使用名词复数是作者推荐的更符合认知直觉的方法。 同时对于元素集合使用更具体的领域名词含义更清晰,若使用抽象的概念名词则表达不清。



为了表达对象间的关联性,有一种方法是体现在 URL 的层级中,但 URL 层级过深并不便于记忆和认知。 这里推荐用 HTTP '?' 后可选参数来表达关联条件,简化 URL 复杂性。




如果可能使用 HTTP 的错误码来映射 API 错误。 HTTP 本身已经定义了广为认知的错误码区间,按类型将错误映射到对应区间对开发人员的学习和认知更友好。 提供尽可能详尽的错误信息。



绝不发布一个不带版本号的 API。关于这点做过软件维护的都明白,有一点细节就是版本号的选择,请使用 v1, v2 整数版本号而非 v1.1 v1.2 这种带小数点版本号机制。这里有个心理认知原因,带小数点的版本通常给人的感觉会频繁变化,而对于一个开放的 API 而言频繁变更绝对是应该避免的,因此不要使用带小数点版本号机制。



当我请求某个对象时不需要其全部属性或需要分页时怎么办?上图中例子已经很好的回答了。



该条针对非资源型 URL 设计而言,因为有些情况就是请求做一个计算,如上图中所示请求金额按币种进行转换。 对于此类 API,使用动词就是合适的,但最好在你的 API 文档中将此类 API 独立分类说明。



开发人员对文件系统的后缀名命名方式都很熟悉了,因此使用后缀名表达响应格式是自然的。 那么默认格式应该选择什么呢?毫无疑问是 JSON,这一点与 javascript 是 Web 端的通用语言有关。



如上,既然我们要照顾 javascript 语言,那么属性命名自然也要采用 javascript 语言传统的驼峰命名法。



简单的搜索可以用资源型 API 来模式化,但全局的搜索 Google 模式大家都很熟悉。



为 API 申请独立的子域名,有且仅有一个是最好的,而且最好是这个域名模式  api.youdomain.com



有了 API 还不够,辅助以 SDK 工具包可以进一步减轻 API 使用者的负担,最重要的是还能避免 API 的误用和低效使用。 其实这里还有一个好处:

Eating your own dog food


作者:mindfloating 发表于2014-6-24 19:20:04 原文链接
阅读:92 评论:0 查看评论

相关 [web api 设计] 推荐:

Web API 设计摘要

- - CSDN博客架构设计推荐文章
最近读了一本微电子书 Brian Mulloy 所著《Web API Design》感觉颇多收获,特对其内容做了个整理摘要以便回顾其观点精华以指导日常工作中的设计思路. 本文主要讲述 Web API 设计,追求一种更务实的 REST 风格. 正如作者所说 REST 是一种架构风格,而非严格的标准,没必要在形式定义上去做过多真论,到底什么才是真正的 REST.

Web API设计方法论

- - 博客园_知识库
  英文原文: A Web API Design Methodology.    为 Web 设计、实现和维护 API 不仅仅是一项挑战;对很多公司来说,这是一项势在必行的任务. 本系列 将带领读者走过一段旅程,从为 API 确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在 Web 上维护公共 API.

Java API 设计清单 « 友好的API

- - 东西
在设计Java API的时候总是有很多不同的规范和考量. 与任何复杂的事物一样,这项工作往往就是在考验我们思考的缜密程度. 就像飞行员起飞前的检查清单,这张清单将帮助软件设计者在设计Java API的过程中回忆起那些明确的或者不明确的规范. 本文也可以看作为“ API设计指南”这篇文章的附录. 我们还准备了一些前后比对的例子来展示这个列表如何帮助你理清设计需求,找出错误,识别糟糕的设计实践以及如何寻找改进的时机.

AT&T公布HTML5 Web应用API

- - HTML5研究小组
北京时间1月10日消息,据国外媒体报道,AT&T首席营销官大卫·克里斯托弗(David Christopher)今天在该公司第六届开发者峰会公布了面向HTML5应用的API(应用编程接口)平台API Catalog. HTML5应用可以在多种设备和移动操作系统上运行.   iPhone版Visual Voicemail将是AT&T的首款网络API.

HTML5 Web Speech API,让网站更有趣

- - SegmentFault 最新的文章
Web API 变得越来越丰富,其中一个值得注意的是 Web Speech API. 传统的网站只能“说”,这个API的出现,让网站能“倾听”用户. 这个功能已经开放了一系列的用法,非常棒. 在这篇文章中,我们将看一下这项技术和建议的用法,以及如何用它来增强用户体验的一些好例子. 声明:本技术比较前沿,目前该规范是W3C的“非官方编辑器的征求意见稿”(截至2014年6月6日).

API 设计二三事

- 烙饼 - 岁月如歌
所有程序员都是 API 设计者. 很认可 Dan Webb 的这句话. 近期刚好也有一些思考,总结分享下. jQuery 很优秀,原由之一就是其 API 具有很强的可预测性. 这样,不用详细阅读文档,根据直觉,就可以推测出 API 的一些高级用法,并且记忆深刻(因为是自己探索发现出来的). 我们可能会好奇,是什么让我们拥有这个“直觉”.

RESTful API 设计指南

- - 阮一峰的网络日志
网络应用程序,分为前端和后端两个部分. 当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信. 这导致API构架的流行,甚至出现 "API First"的设计思想. RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.

Flickr向开发者提供实时Web API

- 品味视界 - cnBeta.COM
Flickr今天向程序员推出了一个名叫Photo Hack Day的活动,释放了一批新的代码和API,让开发人员能够利用Flickr实时访问数据库从而构建新的应用,目前Flickr已经保有60亿张以上的图像. 新的API可以搜索每天上传的数以百万计照片并实时提供,这些数据还包含50多个机构例如美国宇航局,美国国会图书馆,美国和英国国家档案馆的更新.

2013年影响Web发展的五类API

- - 博客 - 伯乐在线
英文原文: 5 APIs that will transform the Web in 2013,编译: CSDN-张红月. 本文作者Alex MacCaw是一名JavaScript 程序员,O’Reilly作者,目前就职于Stripe. 他认为,在接下来的一年,Web领域将会有越来越多的储技术蜂拥而至.

思考系统API设计的问题

- edware_love - C++博客-首页原创精华区
最近正好在思考系统API设计中考量的一些问题,. 我现在的理解是这样的,假设有巨大的真实内存. windows首先将高2G的内存自己占了,用作各种内核对象. 这2G内存共享给每个进程,但进程不能直接访问,只能通过windows给定的函数访问. : 然后每个进程都给他2G内存,进程如果创建自己的对象就放到自己那2G内存里面,如果要建立内核对象就放到共享的那高2G里面去.