前言

RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。本文总结 RESTful 的特点，以及如何设计和使用 RESTful 风格的 API。

RESTful 规范一种软件的架构风格，设计风格，而不是标准，为客户端和服务端的交互提供一组设计原则和约束条件。

正文

面向资源编程

每个 URL 代表一种资源，URL 中尽量不要用动词，要用名词，往往名词跟数据库表格相对应。

一般来说，数据库中的表都是同种记录的集合，所有 API 中的名词也应该使用复数。

举例来说，有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

1
2
3

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

HTTP 动词

对于资源的具体操作类型，由 HTTP 动词表示。
常用的 HTTP 动词有下面五个（括号里对应的 sql 命令）。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

在 URL 中体现版本

例如：

1 2	https://www.bootcss.com/v1/ https://v1.bootcss.com/

在 URL 中体现是否是 API

例如：

1 2	https://www.bootcss.com/api/mycss https://api.bootcss.com/mycss

在 URL 中的过滤条件

如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。

?limit=10：指定返回记录的数量 
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

尽量使用 HTTPS

例如：

1	https://www.bootcss.com/v1/mycss

响应时设置状态码

信息，服务器收到请求，需要请求者继续执行操作
成功，操作被成功接收并处理
重定向，需要进一步的操作以完成请求
客户端错误，请求包含语法错误或无法完成请求
服务器错误，服务器在处理请求的过程中发生了错误

返回值

GET 请求返回查到所有或单条数据

POST 请求返回新增的数据

PUT 请求返回更新数据

PATCH 请求局部更新返回更新整条数据

DELETE 请求返回值为空

返回错误信息

如果状态码是 4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。

1
2
3

{
  "error": "Invalid API key"
}

Hypermedia API

如果遇到需要跳转的情况，携带调转接口的 URL。
Hypermedi API 的设计，比如 github 的 API 就是这种设计，访问 api.github.com 会得到一个所有可用的 API 的网址列表。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

从上面可以看到，如果想获取当前用户的信息，应该去访问 api.github.com/user，就会得到下面的结果。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3/users/#get-the-authenticated-user"
}

其他

（1）API 的身份认证应该使用 OAuth 2.0 框架

（2）服务器返回的数据格式，应该尽量使用 JSON，避免使用 XML

to be continued…