首页 > 代码库 > RESTful API 设计指南

RESTful API 设计指南

 

  网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备……)。

  因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现”API First”的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。本文就简单介绍下RESTful API 的设计指南。

  一、协议

  API与用户的通信协议,总是使用HTTPs协议。

 

  二、域名

  应该尽量将API部署在专用域名之下。

  https://api.example.com

  如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下。

  https://example.org/api/

 

  三、版本(Versioning)

  应该将API的版本号放入URL。

  https://api.example.com/v1/

  另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。

 

  四、路径(Endpoint)

  路径又称”终点”(endpoint),表示API的具体网址。

  在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。

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

  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):从服务器删除资源。

  还有两个不常用的HTTP动词。

  HEAD:获取资源的元数据。

  OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

  下面是一些例子。

  GET /zoos:列出所有动物园

  POST /zoos:新建一个动物园

  GET /zoos/ID:获取某个指定动物园的信息

  PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)

  PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)

  DELETE /zoos/ID:删除某个动物园

  GET /zoos/ID/animals:列出某个指定动物园的所有动物

  DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物

 

  六、过滤信息(Filtering)

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

  下面是一些常见的参数。

  ?limit=10:指定返回记录的数量

  ?offset=10:指定返回记录的开始位置。

  ?page=2&per_page=100:指定第几页,以及每页的记录数。

  ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。

  ?animal_type_id=1:指定筛选条件

  参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

RESTful API 设计指南