RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。
协议
API与用户的通信协议,总是使用HTTPs协议。
域名
尽量将API部署在专用域名之下。
1 | https://api.example.com |
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。
1 | https://example.org/api/ |
版本(Versioning)
应该将API的版本号放入URL。
1 | https://api.example.com/v1/ |
另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。
路径(Endpoint)
路径又称”终点”(endpoint),表示API的具体网址。
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。
例如:
1 | https://api.example.com/v1/zoos // 获取所有动物园信息 |
HTTP动词
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有下面五个(括号里是对应的SQL命令)。
1 | GET(SELECT):从服务器取出资源(一项或多项)。 |
还有两个不常用的HTTP动词。
1 | HEAD:获取资源的元数据。 |
下面是一些例子。
1 | GET /zoos:列出所有动物园 |
过滤信息(Filtering)
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
下面是一些常见的参数。
1 | ?limit=10:指定返回记录的数量 |
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
状态码(Status Codes)
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
1 | 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。 |
状态码的完全列表参见这里。
错误处理(Error handling)
如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
1 | { |
返回结果
针对不同操作,服务器向用户返回的结果应该符合以下规范。
1 | GET /collection:返回资源对象的列表(数组) |
Hypermedia API
RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。
比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档。
1 | {"link": { |
上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型。
其他
(1)API的身份认证应该使用OAuth 2.0框架。
(2)服务器返回的数据格式,应该尽量使用JSON,避免使用XML。
实践总结
- 使用http或https协议
- API可以是特定的域名,有的也可以使用主域名。
- 将API的版本号放入URL。
- URL不能有动词,只能有名词,应该使用复数。
- 对于资源的具体操作类型,由HTTP动词表示。
- 常用的HTTP动词有POST、GET、PUT、DELETT,分别对应CRUD(增删改查)。
- 分页、排序、筛选等在过滤信息(Filtering)中显示,即query参数
- 常使用的状态码有:200 OK/401 Unauthorized/403 Forbidden/404 NOT FOUND/500 INTERNAL SERVER ERROR
- 错误处理:返回的信息中将error作为键名,出错信息作为键值。
- 针对不同操作,服务器向用户返回符合规范的结果。
- RESTful API最好做到Hypermedia,一般去做,但会有API管理系统或文档。