[PHP][API]Chapter 6: API Design

本章节标志一个转折点在我们了解 APIs 的过程中。我们已经了解了组成部分，现在我们将了解如何将概念结合起来，形成一个 API。在这一章节里，我们将通过设计一个 API 来探讨 API 的组成元件。

组织数据

国家地理预计，在2011年，美国人将拍 80 亿张照片。随着这么大量的照片数量，你能想象每个人都使用不同的办法整理这些照片。有些人喜欢把所有东西放到一个单一的文件夹中。有些人会按照年份、月份、事件的文件夹的层次结构来分类。

公司在组织上也有相似的想法，当建立它们的他们的 APIs 时。正如我们在第一章提到的，API 的目的是让电脑与公司的数据跟容易配合。显而易见，一个公司可以决定使用一个单一的 URL 对于所有数据并且使他们可以方便搜索（比如像把你所有的照片放到一个文件夹）。另一种方式，每一种数据有它自己的 URL ，在层级组织中（就像照片有它的文件夹和子文件夹）。每家公司选择最好的方式构建它们的 API 应对不同的形式，在现有的行业经验引导下。

选择一种形式开始

当讨论 APIs 的时候，你可能会听到“soap”和“rest”的说法，并且很疑惑这个开发商到底是在工作还是计划休假。事实是这些是基于网络的 API 的两个常见体系的名称。SOAP（acronym 的缩写）是一种基于 XML 的设计，拥有标准化的结构来请求和响应。REST，代表表述性转移，是一个比较开源的，提供了大量的协定，但是留下许多需要在设计 API 时候商榷的地方。

通过这个课程，你可能主要到我们更偏爱 REST APIs。这种偏爱是大多数的，因为 REST 采用令人难以置信的速度。这并不是说 SOAP 是邪恶的，它也有它的优势。尽管如此，我们的讨论焦点依然停留在 REST ，因为这是你最可能碰见的 API 。在剩下的部分，我们将了解组件通过做一个 REST API。

我们的第一个资源

回想第2章节，我们聊了一点关于资源的事情。回想一下，资源就是 API 的名词（顾客和披萨）。这些都是我们希望世界通过 API 交互的东西。

为了感受一个公司是如何开始设计 API 的，让我们尝试联系起我们的披萨店。

对于客户端，以便能够与披萨店联系起来，我们需要做几件事：

1. 决定什么资源是可用的。
2. 分配 URL 到这些资源。
3. 决定客户端应该对这些资源可以进行什么样的动作。
4. 找出每一步需要哪些数据，他们应该是什么样的格式。

获取资源是第一个艰难的任务。一个解决这个问题的方法就是逐步执行典型的相互作用。对于披萨店来说，我们可能又一个菜单。在菜单上是各种披萨。当顾客想要我们我们做其中一种蛋糕，他们需要下订单。在这方面，菜单，披萨，顾客和订单听起来是不错的资源。让我们从订单开始。

下一步就是分配这些 URL 到资源。有很多的肯能性，但幸运的是 REST 约定给予了一定支持。在一个典型的 REST API ，资源将分配两个 URL 。首先是资源的名称的复数，如 /orders 。第二个是资源名称的复数加一个唯一的标识符指定单个资源，如  /orders/ ,其中 是一个命令的唯一标识符。这两个 URL 模式构成了我们的 API 将支持第一端点。这些被称为端点的，仅仅因为他们放在了 URL 的末端，如 http://example.com/ 。

由于我们选择了资源并分配了 URL ，我们需要决定客户端可以采取什么样的行动执行。根据 REST 的约定，我们可以知道复数端点( /orders ) 用于列出现有的订单和创造新的订单。有一个唯一标识符的端点（ /orders/ ），用来检索、更新或取消一个特定的顺序。客户端告诉服务端通过 HTTP 通道将传输什么样的动作（GET、POST、PUT、DELETE）在请求中。

总之，我们的 API 现在看起来是这样的：

| HTTP verb | Endpoint | Action |

| ——— | ——— | ———————— |

| GET | /orders | List existing orders |

| POST | /orders | Place a new order |

| GET | /orders/1 | Get details for order #1 |

| GET | /orders/2 | Get details for order #2 |

| PUT | /orders/1 | Update order #1 |

| DELETE | /orders/1 | Cancel order #1 |

充实我们的订单端点的动作，最后一步是决定客户端和服务端之间需要交换什么数据。借用我们在第3章节中的披萨店的例子，我们能说一个订单需要一个面包皮和夹心的种类。我们还需要选择客户端和服务端之间传递信息的数据格式。XML 和 JSON 都是很好的选择，但对于可读性，我们选择 JSON。

在这一点上，你已经设计了一个功能性的 API 。下面是客户端和服务端使用 API 进行交互的样子：

把资源连接在一起

我们的披萨店的 API 看起来很尖锐。订单以前所未有的方式进来。事实上，生意是非常的好，我们决定要开始根据顾客的忠诚度来跟踪订单了。一个简单的新方法做到这一点就是增加一个新的客户资源。

就像订单一样，我们的客户资源需要一定的端点。如以下约定， /customers 和 /customers/ 很好的锲合。我们跳过这些细节，但我们假设我们的每个行为为每个端点添加意义，哪些数据代表一个客户。假设我们做了一切，我们又一个有趣的问题：我们如何让订单和用户发现联系？

REST 从业者执着于如何解决资源相关联的问题。有人说，层次结构应该继续增加，增加端点就像 /customers/5/orders 指第五个顾客的订单， /customers/5/orders/3 指第五个顾客的第三个订单。其他人则认为应该让事情变得更简单一些，通过在一个数据相关的详细信息。在这种模式下，创建订单 custonmer_id 可附带订单信息。这两种在使用 REST APIs 中都比较广泛，所以都值得了解一下。

搜索数据

随着一个系统数据的增加，端点列出所有的记录变得不切实际。试想一下，如果我们的披萨店有 300 万 完成的订单，你想了解有多少的浇头为辣香肠。发送一个 GET 请求给 ／orders 并且收到所有 300 万订单将变得没有用。幸运的是，REST 有个极好的方法搜索数据。

URLs 有一个我们没有提到过的组件，query sting （查询字符串）。查询是指搜索和字符串表示的文本。查询字符串是一些文本，去到一个 URL 的末尾，通过 URL 传递信息。例如，在问号之后的信息都是查询数据： http://example.com/orders?key=value 。

REST API 使用查询字符串来定义搜索的细节。这些细节被称为查询参数。API 决定它将接收什么参数，需要使用这些确切名称实现搜索。我们的披萨店 API 允许客户端搜索订单通过 URL : http://example.come/orders?topping=pepperoni 。客户端又可以通过列出一个有一个参数进行查询，用符号（“&”）隔开，查询多个参数。例如： http://example.com/orders?topping=pepperoni&crust=thin 。

查询串的另一个用途时要限制在每个请求中返回的的数据数量。通常，API 将结果分成组（100或500的记录）中，在一个时间内返回一组。这些分割了的数据的过程被称为分页（比喻将单词组成页）。允许客户端翻阅所有数据，该 API 将支持查询参数允许客户端置顶它想要的数据页面。在我们的披萨店 API ，我们可以通过支持分页，允许客户指定两个参数：页面和大小。如果客户端使的请求像 GET／orders?page=2&size=200 ，我们都知道他们想要结果是第二页，每页 200 个结果，订单 201-400。

第六章小结

在本章节，我们学习了如何设计一个 REST 的 API。我们发现了 API 支持的基本功能，以及如何组织数据，以便它可以被计算机容易吸收。

我们所了解的关键点：

• SOAP : API 架构标准化的信息格式。
• REST : 控制资源中心的 API 架构。
• Resource :API 项目的一个名词就像顾客和订单。
• Endpoint ：构成一部分 API 的 URL。在 REST 中，每个资源都有自己的端点。
• Query String ：用于数据传递给服务器的 URL 的一部分。
• Query Parameters ：在查询字符串中发现的值（topping＝cheese）。
• Pagination ：分离结构到管理模块的过程。