一些 REST 最佳实践

标签: rest 最佳实践 | 发表时间:2015-08-10 13:23 | 作者:
出处:http://colobu.com/

原文: Some REST best practices, 作者: Pierre-Olivier Bourgeois
译文: 一些REST最佳实践, 译者: yongx

如今,REST APIs 已经非常普遍,几乎所有WEB应用都用到了它们。提供简单,一致,实用的API是种义务,方便其它人很容易的使用。即使下面的这些规范,在你看来很正常,我经常看到人们不遵守它。这是我写这篇文章的原因。
当你设计 RESTful API 时,下面是一些应该牢记的最佳规范。
免责声明:下面的这些规范是根据过去的经验,我认为最好的。如果你有别的想法,咱们邮件讨论。

给API加上版本

API版本应该是必备的。这样API不会随时间过时。一种方法是把版本放到URL里( /api/v1...)

另一个巧妙的花招是使用 Accept HTTP header,来传递需要的版本,正如 github所做的
(备注:Github 的格式是,application/vnd.github[.version].param[+json],version指定版本,param是想要的格式,txt,html等。从评论看似乎Github的方式更完美)

通过版本,你可以改变API的结构,而不用担心老版客户端的兼容问题。(备注:API提供者默默承受维护多套API的痛苦)

使用名词,而不是动词

我经常看到有人使用动词而不是名词来表示资源名称,例如下面这些:

  • /getProducts
  • /listOrders
  • /retreiveClientByOrder?orderId=1

从结构整洁和一致角度考虑,你应该总是使用名词。而且,巧妙使用 HTTP 方法(GET,POST)可以把想要的操作从资源名称上去除。如下面的例子:

  • GET /products 返回所有产品列表
  • POST /products 添加产品到产品列表
  • GET /products/4 提取Id为4的产品
  • PATCH/PUT /products/4 更新Id为4的产品

使用复数形式

在我看来,同一资源命名,混合使用单数和复数形式不是好主意。很快就会混淆,带来不一致。
即使对 show/delete/update 操作,使用 /artists 而不是 /artist 也更好点。

GET 和 HEAD 操作应该是安全的(无副作用)

RFC2616 明确规定 HEADGET 必须是安全的(不能改变资源状态)
右边是一个不好的例子: GET /deleteProduct?id=1
如果搜索引擎检索了那个页面,画面太美我不敢看(备注:实践中对删除操作都有权限验证,就算操作引擎抓取也没啥破坏)
(备注: POSTPUT的区别, POST是不幂等的, PUT是幂等的。如果多次调用URL得到的结果都一样,那就是幂等的。例如,发评论,如果评论ID在提交评论前已经生成,那么无论点多少次提交,看到的都是一条评论。如果评论ID在提交评论后生成,点多少次提交就看到多少条评论。)

使用嵌套资源

如果想获取全部的子集,使用嵌套路由来让风格简洁。例如想从所有唱片中选取特定的,使用 GET /artists/8/albums(备注:这里8就是所谓嵌套路由,指导选取哪个唱片)

分页

通过 HTTP 返回超大结果集不是好主意。序列化大的JSON数据很慢,这会导致性能问题。
通常的做法是分页,Facebook,Twitter,Github都是这么做的。提取少里数据更快,就算需要多次调用,也比一次提取很大(但执行很慢)的数据更高效。
如果想分页,一个好的方法是通过 Link HTTP header,来提示前一页和后一页。正如 Github 做的那样
(备注: Link的用法 Link: http://next_url; rel="next", http://last_url; rel="last", http://first_url; rel="first", http://prev_url; rel="prev")

使用合适的 HTTP 状态码

请求返回时,无论请求成功与否,总是使用正确的返回码。下面是一些可能用到的状态码。

成功状态码(2XX系列)

  • 201 Created 当成功创建资源时(INSERT)
  • 202 Accepted 当请求被接受,并放到后台执行时(异步任务)
  • 204 No Content 当请求成功,但是没有内容返回时(例如 DELETE 时)

客户端错误(4xx系列)

  • 400 Bad Request 当处理querystring或http body时出错(例如非法JSON)
  • 401 Unauthorized 认证失败
  • 403 Forbidden 认证成功时,操作或请求的资源不被允许
  • 406 Not Acceptable 请求格式不被接受(例如试图请求JSON数据,但服务器只提供XML)
  • 410 Gone 请求的资源被永久删除(备注:咋判断是不存在还是被永久删除了)
  • 422 Unprocessable entity 当创建对象时发生可用性错误

完整的状态码请参照 RFC2616

总是返回一致的错误内容

当发生错误时,总是返回一致的错误描述。错误结构总是相同,这样更容易解析错误信息。
如下描述,清晰,简单,自说明

     
1
2
3
4
5
6
     
HTTP/1.1 401 Unauthorized
{
"status": "Unauthorized",
"message": "No access token provided.",
"request_id": "594600f4-7eec-47ca-8012-02e7b89859ce"
}

相关 [rest 最佳实践] 推荐:

一些 REST 最佳实践

- - 鸟窝
原文: Some REST best practices, 作者: Pierre-Olivier Bourgeois. 译文: 一些REST最佳实践, 译者: yongx. 如今,REST APIs 已经非常普遍,几乎所有WEB应用都用到了它们. 提供简单,一致,实用的API是种义务,方便其它人很容易的使用.

jQuery最佳实践

- andi - 阮一峰的网络日志
上周,我整理了《jQuery设计思想》. 那篇文章是一篇入门教程,从设计思想的角度,讲解"怎么使用jQuery". 今天的文章则是更进一步,讲解"如何用好jQuery". 我主要参考了Addy Osmani的PPT《提高jQuery性能的诀窍》(jQuery Proven Performance Tips And Tricks).

PHP最佳实践

- xiangqian - 阮一峰的网络日志
虽然名字叫《PHP最佳实践》,但是它主要谈的不是编程规则,而是PHP应用程序的合理架构. 它提供了一种逻辑和数据分离的架构模式,属于MVC模式的一种实践. 我觉得,这是很有参考价值的学习资料,类似的文章网上并不多,所以一边学习,一边就把它翻译了出来. 根据自己的理解,我总结了它的MVC模式的实现方式(详细解释见译文):.

MongoDB最佳实践

- - NoSQLFan
将 MongoDB加入到我们的服务支持列表中,是整个团队年初工作计划中的首要任务. 但我们感觉如果先添加一项对NoSQL存储的支持,而不是先升级已支持的关系型数据库,可能对用户不太好,毕竟目前的用户都使用关系型数据库. 所以我们决定将引入MongoDB这项工作放到升级MySQL和PostgreSQL之后来做.

经典论文 — REST

- ripwu - kernelchina
牛人Roy Thomas Fielding的博士论文,此处可以访问到英文版,中文版可以google一下. HTTP1.0,1.1版本以及URI规范的主要作者,Apache的co-founder. 在写这篇论文之前已经很牛了,笔者不明白的是这种档次牛人还要读博士,文凭有这么重要吗. 文中没有任何令人眼花的数学公式和统计图表,实际上是一篇描述URI,HTTP设计经验教训总结的文章.

MongoDB REST Api介绍

- peigen - NoSQLFan
MongoDB默认会开启一个HTTP协议的端口提供REST的服务,这个端口是你Server端口加上1000,比如你的Server端口为27017,那么这个HTTP端口就是28017,默认的HTTP端口功能是有限的,你可以通过添加–rest参数启动更多功能. 下面是在这个端口通过其RESTFul 的API操作MongoDB数据的几个例子,来源是MongoDB官方文档.

WebSockets与REST之争?

- - 酷勤网-挖经验 [expanded by feedex.net]
WebSockets变得越来越流行并积累了不少用户. 去年年底,WebSockets成为了. W3C的推荐候选,这使得其向标准更迈进了一步. Oracle等其他厂商最近也提交了申请,来启动在Java企业版的下一个版本中引入WebSockets(. JSR 356)的标准流程工作. 绝大部分的主流浏览器,如Chrome、Firefox、Safari和IE,都支持某个WebSockets修正本,并最终会采用最后成形的标准.

文章: Grails最佳实践

- - InfoQ cn
我在IntelliGrape工作,这是一家专门使用Groovy & Grails进行开发的公司. 本文是我们Grails项目遵循的最佳实践的基本清单,收集自邮件列表、Stack Overflow、博文, 播客和 IntelliGrape的内部讨论. 它们分为控制器、服务、Domain、视图、TagLib、测试和其他.

PHP最佳实践(译)

- - CSDN博客Web前端推荐文章
原文:  PHP Best Practices-A short, practical guide for common and confusing PHP tasks. 译者: youngsterxyf. 本文档最后审阅于2013年3月8日. 由我, Alex Cabal,维护该文档. 我编写PHP程序已有很长一段时间了,当前我 经营着 Scribophile,由认真作家组成的一个在线写作团体,  Writerfolio,为自由职业者提供的一个易用写作工具集,以及  Standard Ebooks,一个图文并茂、无数字版权管理的公共领域电子书出版商.