欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识！
您现在的位置是： 首页

RESTful API 设计

程序员文章站 2024-03-22 09:28:10
...

今天，我将介绍RESTful API的设计细节，探讨如何设计一套合理、好用的API。我的主要参考了两篇文章（1，2）。

RESTful API 设计

一、协议

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

二、域名

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

 
  1.  

  2. https://api.example.com

  3.  

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

 
  1.  

  2. https://example.org/api/

  3.  

三、版本（Versioning）

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

 
  1.  

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

  3.  

另一种做法是，将版本号放在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 的含义是相同的。

七、状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
  • 204 NO CONTENT - [DELETE]：用户删除数据成功。
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
  • 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

状态码的完全列表参见这里。

八、错误处理（Error handling）

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

 
  1.  

  2. {

  3. error: "Invalid API key"

  4. }

  5.  

九、返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

  • GET /collection：返回资源对象的列表（数组）
  • GET /collection/resource：返回单个资源对象
  • POST /collection：返回新生成的资源对象
  • PUT /collection/resource：返回完整的资源对象
  • PATCH /collection/resource：返回完整的资源对象
  • DELETE /collection/resource：返回一个空文档

十、Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

 
  1.  

  2. {"link": {

  3. "rel": "collection https://www.example.com/zoos",

  4. "href": "https://api.example.com/zoos",

  5. "title": "List of zoos",

  6. "type": "application/vnd.yourformat+json"

  7. }}

  8.  

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

 
  1.  

  2. {

  3. "current_user_url": "https://api.github.com/user",

  4. "authorizations_url": "https://api.github.com/authorizations",

  5. // ...

  6. }

  7.  

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

 
  1.  

  2. {

  3. "message": "Requires authentication",

  4. "documentation_url": "https://developer.github.com/v3"

  5. }

  6.  

上面代码表示，服务器给出了提示信息，以及文档的网址。

十一、其他

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

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

 

 

RESTful API 设计指南——最佳实践

Facebook、谷歌、Github、Netflix 和几个其他的科技巨头已经允许开发者和其产品通过 API 调用他们的数据，并为他们提供平台。即使你不是写 API 的专业人士，拥有精美的 API 也对你的应用程序有好处。

关于设计 API 的最好方法，网络上有较长一段时间的争论，但官方也没有对此给出解释。

API 是一个接口，通过它许多开发者可与数据交互。 设计优良的 API 使用起来很方便，并给开发者的工作带来便利。 API 是开发者的 GUI，如果它设计不合理，开发者会将它替换。所以，开发者的经验是衡量 API 质量的最重要的指标。

--API就像一个在舞台上表演的艺术家，其用户就是其观众

 

1) 术语

 

以下是与 REST API 相关的重要术语：

  • 资源（Resource） 是一个对象或对某物的表示。它有一些相关联的数据，并有一组方法进行操作。 例如：动物，学校和员工是资源。这些资源都有着删除，添加，更新操作。

  • 集合（Collection）是一系列资源，例如：公司集合是很多公司的集合。

  • URL（统一资源定位符）是一种路径，可以通过它定位资源并且也可以对它执行一些动作。

2) API 端点（路径）

为了更好理解，我们给公司写 API，这些公司都有一些员工。/getAllEmployees 是对员工列表进行回应的 API。公司其他 API 大致如下:

  • /addNewEmployee

  • /updateEmployee

  • /deleteEmployee

  • /deleteAllEmployees

  • /promoteEmployee

  • /promoteAllEmployees

并且将有大量的和这些操作不同的 API 端点，它们包含大量冗余的行为。因此，当 API 数量增加时，这些 API 端点将很难维护。

哪里不对？

每个 URL 代表一种资源（Resource），所以 URL 中只能有名词，不能有动词。 API 路径 /addNewEmployee 包含了操作 addNew 和资源名称 Employee。

那么怎样算是正确的方式？

/companies 是一个很好的不包含操作的例子。但是问题来了，我们该怎样告诉服务器我们要进行的操作呢？新增，删除，还是更新？

这时 HTTP 方法（GET，POST，DELETE，PUT）（也称为动词）就可以起到作用了。

资源在 API 端点中应该总是复数，如果我们想访问资源的一个实例，我们可以传递 URL 中的 id。

  • 方法 GET 路径 /companies 是获取所有公司的列表。

  • 方法 GET 路径 /companies/34 是获取公司34的详细信息。

  • 方法 DELETE 路径 /companies/34 是删除公司34.

在其他的一些使用案例中，如果我们有一些资源在某个资源之下，例如，一个公司的员工，那么在这样的例子中 API 的 endpoint（端点） 就应该是这样的：

  • GET /companies/3/employees 可以取得编号为3的公司的员工列表

  • GET /companies/3/employees/45 可以取得编号为3的公司的45号员工的细节信息

  • DELETE /companies/3/employees/45 可以删除编号为3的公司的45号员工

  • POST /companies 可以创建一个新公司并返回新创建公司的细节信息

现在这样，API 是不是更严谨和一致了呢？

结论：路径应该包含资源的复数形式，HTTP 方法应该定义成各种行为在资源上执行。

3) HTTP 方法 (动词)

HTTP 定义了几组方法，这些方法给出了对资源要执行的操作类型。

--URL 是一个句子，其中资源是名词，HTTP 方法是动词。

 

主要的HTTP方法如下： 

  1. GET 方法从资源请求数据，不产生多余结果。
    例如： /companies/3/employees 会返回公司3的所有雇员列表。

  2. POST 方法请求服务器在数据库中创建资源，这主要用于提交 Web 表单时。
    例如： /companies/3/employees 创建一个公司3的新雇员。 
    POST 是非幂等的，这意味着多个请求将会有不同的效果。

  3. PUT 方法请求服务器更新资源或创建资源（如果不存在的话）。
    例如： /companies/3/employees/john 将请求服务器在公司3的雇员集合中更新或在不存在的情况下创建关于 john 的资源。
    PUT 是幂等的，这意味着多次请求具有相同的效果。 

  4. DELETE 方法将请求的资源或实例从数据库中删除。
    例如： /companies/3/employees/john/ 将请求服务器从公司3的雇员集中删除 john 资源。

HTTP 中还有很多其他方法，我们将在另一篇文章中讨论。

4) HTTP 响应状态码

当客户端通过 API 向服务器发起请求时，无论请求是失败的、通过的还是错误的，客户端应该获得反馈。HTTP 状态码是一堆标准化的数值码，在不同的情况下具有不同的解释。服务器应始终返回正确的状态码。

以下是 HTTP 状态码的主要分类：

2xx (成功类别)

这些状态代码表示请求的操作已被服务器接收到并成功处理。

  • 200 Ok：标准的 HTTP 响应，表示 GET、PUT 或 POST 的处理成功。

  • 201 Created：在创建新实例时，应返回此状态代码。例如，使用 POST 方法创建一个新的实例，应该始终返回 201 状态码。

  • 204 内容不存在：表示请求已被成功处理，但并未返回任何内容。

DELETE算是其中一个很好的例子。

API DELETE /companies/43/employees/2 将删除员工 2，作为响应，我们不需要在该 API 的响应正文中的任何数据，因为我们明确地要求系统将其删除。如果有任何错误发生，例如，如果员工 2 在数据库中不存在，那么响应码将不是 2xx 对应的成功类别，而是 4xx 客户端错误类别。

3xx (重定向类别)

  • 304 未修改：表示客户端的响应已经在其缓存中。 因此，不需要再次传送相同的数据。

4xx (客户端错误类别)

这些状态代码表示客户端发起了错误的请求。

  • 400 错误请求：表示客户端的请求没有被处理，因为服务器不能理解客户端请求的是什么。

  • 401 未授权：表示客户端不被允许访问该资源，需要使用指定凭证重新请求。

  • 403 禁止访问：表示请求是有效的并且客户端已通过身份验证，但客户端不被允许以任何理由访问对应页面或资源。 例如有时授权的客户端不被允许访问服务器上的目录。

  • 404 未找到：表示所请求的资源现在不可用。

  • 410 资源不可用：表示所请求的资源后续不再可用，该资源已被移动。

5xx（服务器错误类别）

  • 500是服务器内部错误，表示请求已经被接收到了，但服务器被要求处理某些未预设的请求而完全混乱。

  • 503服务不可用表示服务器已关闭或无法接收和处理请求。大多数情况是服务器正在进行维护。

5) 字段套管约定

您可以遵循任何套管约定，但要确保其在应用程序中一致。如果请求主体或响应类型是JSON，那么请按照camelCase(驼峰命名法)来保持一致。

6) 搜索、排序、过滤和分页

这些行为都只是针对一个数据集进行的查询。由于还没有一套新的 API 来处理这些行为。因此，我们需要向 GET 方法的 API 附加查询参数。

我们来理解几个例子看它们是如何实现这些行为的。

  • 排序(sorting)，客户端想要获得排序后的公司列表，GET /companies 端点应当接受多个查询排序参数。
    例如，GET /companies?sort=rank_asc 将根据等级以升序的方式对公司进行排序。

  • 过滤（Filtering），用来过滤数据集，我们可以通过查询参数传递不同的选项。
    例如，GET /companies?category=banking&location=india 将根据公司类别为银行以及所处位置为印度来过滤公司的列表数据。

  • 搜索（Searching），当需要在公司列表中搜索公司名称时，API 端点应当是 GET /companies?search=Digital Mckinsey。

  • 分页（Pagination），当数据集太大时，我们将数据集分成更小的块，这样有助于提高性能，并且更易于处理响应。 例如，GET /companies?page=23 表示获取第 23 页的公司列表。

如果在 GET 方法中附加了很多查询参数，会造成 URI 太长，服务器可能会响应 414 的 HTTP 状态，表示这个 URI 太长，在这种情况下，我们也可以将参数传递给 POST 方法的请求体中。

7) 版本控制

当你的 API 被开始被广泛使用后，突然升级API会打破现有的产品、服务。

http://api.yourservice.com/v1/companies/34/employees 是一个很好的例子，它的路径中有API的版本号。如果有任何重大的中断更新，我们可以将新的API集命名为v2或v1.x.x

上一篇： Java学习手册：实例化String对象

下一篇： Javascript学习笔记：DOM事件

推荐阅读