RESTful API设置教程

遵循REST原则设置WEB服务的API，已逐渐成为业界主流，由于 REST 可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化应用系统之间的集成也逐渐成为一套比较成熟的互联网应用程序的API设计理论，本文将阐述REST的设计标准及场景应用等相关知识。

1. 什么是REST？

REST即表述性状态传递（英文：Representational State Transfer，简称REST）是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格；它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。表述性状态转移是一组架构约束条件和原则；满足这些约束条件和原则的应用程序或设计就是RESTful。需要注意的是，REST是设计风格而不是标准。

2. 版本

版本更多人选择放在HTTP头信息中，但是比较直观的是放URL上，例如：

1	http://api.minhow.com/v1/

(个人偏好放在头部请求中)。

3. HTTP动词

RESTful API设计的第一步，是充分了解常用的HTTP动词，常用的HTTP动词有下面五个：

GET: 读取资源 (safe & idempotent)
PUT: 替换资源 (idempotent)
DELETE: 删除资源 (idempotent)
POST: 新增资源
PATCH: 更新资源部份內容

详细的介绍可以查看我的上篇文章REST模式：POST，GET，PUT，DELETE，PATCH的含义与区别
还有两个不常用的HTTP动词

1 2	HEAD：类似GET，但只回传HTTP header。 OPTIONS：获取信息。

以上的[safe]是指操作不会改变服务器的资源状态，[idempotent]是幂等的意思，指该操作不管做1遍还是N遍，都会得到相关的资源结果。

4. URL设置

URL中一般只使用名词来指定资源，名词一般也是复数形式，原则上不使用动词；“资源”是REST架构或者说整个网络处理的核心。下面是一些例子：

GET /books：列出所有书籍
POST /books：新建一本书籍
GET /books/book_id：获取某本书籍的信息
PUT /books/book_id：更新某本书籍的全部信息
PATCH /books/book_id：更新某本书籍的部分信息
DELETE /books/book_id：删除某本书籍
GET /books/book_id/authors：列出某本书籍的所有作者
DELETE /books/book_id/authors/author_id：删除某本书籍的某个作者信息

5. 过滤信息

一般我们请求返回的数据会比较多，需要对返回结果进行相对应的过滤，下面列出一些常用的参数过滤方法：

?offset=1&limit=10：  分页方法，offset指定返回记录的当前页，limit指定返回记录的数量，也可以使用下面的例子：
?page=2&per_page=100： page指定第几页，per_page每页的记录数，看个人爱好选择合适的使用。
?sort=book&order=desc： 排序方法，sort指定返回结果按照哪个属性排序，order排序顺序，如果多个属性排序可以用逗号隔开，例：book,author；排序顺序同上。
?fields=name,age,sex： 指定返回的数据，该方法主要是在返回数据量较多的情况下选择返回指定的数据，也是用逗号隔开。
search?q={keywords}： 查找方法，q指定查找的关键词。

6. HTTP状态码

2xx: 成功
200 OK: 通用状态码
201 Created: 资源新增成功
202 Accepted: 请求已接受，但尚在处理中
204 No Content: 请求成功，但未回传任何內容
3xx: 重新导向
301 Moved Permanently: 资源已移至它处
303 See Other: 回传的內容可在它出取得（例如在用户端发送了一个POST请求之后）
304 Not Modified: 请求的资源并未修改
4xx: 用户端错误
400 Bad Request: 通用状态码
401 Unauthorized: 用户端尚未认证
403 Forbidden: 用户端被禁止此请求
404 Not Found: 请求的资源不存在
405 Method Not Allowed: 不支持请求的HTTP方法
406 Not Acceptable: 不支持请求所要求的內容类型（Accept表头）
415 Unsupported Media Type: 不支持请求所用的內容类型（Content-Type表头）
5xx: 服务器错误
500 Internal Server Error: 工程师找到了BUG
501 Not Implemented: 用戶端的请求目前未支持
502 Bad Gateway: 上游的服务器未回传正确结果，一般是gateway或proxy server才会回传此状态码
503 Service Unavailable: 暂停服务
504 Gateway Timeout: 上游的服务器超时，一般是gateway或proxy server才会回传此状态码

关于几个容易混淆的状态码，补充说明如下：
401、403: 401是指用户端尚未认证，也就是unauthenticated；403是指用户端目前的身份不被允许此项请求（通常是用户端已经认证过了），或是所有使用者都不被允许此项请求。
406、415: 406是指用户端要求「回传」的Content-Type（也就是用户端在Accept表头里所要求的），服务器不支持；415是指用户端送出的「请求」，其Content-Type（也就是用户端HTTP request body的內容類型），服务器不支持。
另外要注意，这些回传的状态码，是代表API这一层的执行状态，例如当/search?q=xyz查找结果是空的，API结果仍应该回传200，而非404；因为从API角度来看，/search这个「资源」存在，而且API执行成功。

7. HTTP Header

用户端请求服务器时，可能会带一些HTTP header，标准的内容协商方式是使用 HTTP 头；我们通常使用 Accept 来设置我们接受的返回结果的内容格式，用 Accept-Charset 来设置字符集，用 Accept-Encoding 来设置数据传输格式，用 Accept-Language 来设置语言。

8. 请求和响应格式

请求：三种比较流行的数据提交方式，application/x-www-form-urlencoded (网页表单预设，不能用于上传数据)，multipart/form-data (如果要包含上传数据的话，使用这个)，application/json (不能用于上传数据)。
响应：JSON和XML比较流行，JSON 目前最流行的格式，服务器返回的格式尽可能的使用这种格式，因为JSON格式处理上较简洁，所以越来越多人采用这个格式，避免使用XML格式。

9. 认证设计和安全性

认证最好使用OAuth 2.0框架，详细认证方式，请点开链接查看。
（1）使用SSL协议，在传输层对数据加密。（2）数据加密，可采用HMAC签名，RSA加密等方法。

10. 相关案例

API文件案例：
http://dojotoolkit.org/api     Dojo API开发文档
https://developer.github.com/v3   github API开发
https://developer.paypal.com/docs/api  paypal API开发文档
https://dev.twitter.com/rest/public   twitter API开发文档
https://developers.facebook.com/docs/graph-api  facebook API开发文档
API设计指南：
https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md
https://geemus.gitbooks.io/http-api-design/content/en/