Web API 设计摘要
近期读了一本微电子书 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
Web API 设计摘要的更多相关文章
- GOTO Berlin: Web API设计原则
在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...
- 我所理解的RESTful Web API [设计篇]
<我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...
- Web API设计
Web API设计经验与总结 在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建. 通过Http协议的形式来. ...
- Web API设计方法论
英文原文:A Web API Design Methodology 为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定 ...
- Web API设计方法论--比较完整的web api 开发过程
为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护 ...
- Web API 设计
Web API 设计 The Design of Web APIs free online ebook https://www.manning.com/books/the-design-of-web- ...
- 我所理解的RESTful Web API [设计篇]【转】
原文:http://www.cnblogs.com/artech/p/restful-web-api-02.html <我所理解的RESTful Web API [Web标准篇]>Web服 ...
- RESTFUL如何指导WEB API设计?
博主刚刚接触web开发的时候,写了一个接口 /get_article_info/1 获取id为1的这篇文章的内容,被前辈们看见了,前辈给我说我这个接口设计的不太好啊,不符合RESTFUL规范,当前辈们 ...
- 移动互联网实战--Web Restful API设计和基础架构
前言: 在移动互联网的大潮中, Web Restful API逐渐成为Web Server重要的一个分支. 移动端和服务端的交互, 主流的方式还是通过Http协议的形式来进行. 请求以Get/Post ...
随机推荐
- JSP 和 Servlet 有哪些相同点和不同点, 他们之间的联系是什么?
jsp和servlet的区别和联系:1.jsp经编译后就变成了Servlet.(JSP的本质就是Servlet,JVM只能识别java的类,不能识别JSP的代码,Web容器将JSP的代码编译成JVM能 ...
- 常用类库之.NET中的字符串
字符串的特性 .不可变性 由于字符串是不可变的的,每次修改字符串,都是创建了一个单独字符串副本(拷贝了一个字符串副本).之所以发生改变只是因为指向了一块新的地址. .字符串池(只针对字符串常量) 当一 ...
- python第一步
安装2.7的python 环境:到cmd下python,就可以跑代码了,要是想运行py文件,在命令行python test.py,记得在windows下把python加入环境变量 学习基础的语法: 注 ...
- java从c struct传来的字节数组中取值
public int getInt(byte[] array,int index) { return (array[index] & 0xff) | (array[index + 1] & ...
- 转: Transact-sql游标使用详解~~很详细
/*原理:游标就是把数据按照指定要求提取出相应的数据集,然后逐条进行数据处理.1.1游标的概念 游标(Cursor)它使用户可逐行访问由SQL Server返回的结果集. 使用游标(cursor)的一 ...
- Hibernate Dialect must be explicitly set
在偶然一次运行hibernate测试类的时候,出现如下错误,Exception in thread "main" org.hibernate.HibernateException: ...
- hdu 4119 Isabella's Message
Isabella's Message Time Limit: 2000/1000 MS (Java/Others) Memory Limit: 32768/32768 K (Java/Others) ...
- Jedis中的一致性hash
Jedis中的一致性hash 本文仅供大家参考,不保证正确性,有问题请及时指出 一致性hash就不多说了,网上有很多说的很好的文章,这里说说Jedis中的Shard是如何使用一致性hash的,也为大家 ...
- 初次接触VC++载入自己定义LIB 即静态链接
分为两部分 第一部分 LIBproject 用来生成LIB文件 #ifndef _myfun #define _myfun int myfun(int x,int y) { return x+y; ...
- :before :after
#p1:before{ content: "哈哈哈 "; color: red;}#p1:after{ content: "哈哈哈"; color: #452d ...