[PHP][API]Chapter 6: API Design
组织数据
国家地理预计，在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 的，让我们尝试联系起我们的披萨店。
对于客户端，以便能够与披萨店联系起来，我们需要做几件事：
- 决定什么资源是可用的。
- 分配 URL 到这些资源。
- 决定客户端应该对这些资源可以进行什么样的动作。
- 找出每一步需要哪些数据，他们应该是什么样的格式。
获取资源是第一个艰难的任务。一个解决这个问题的方法就是逐步执行典型的相互作用。对于披萨店来说，我们可能又一个菜单。在菜单上是各种披萨。当顾客想要我们我们做其中一种蛋糕，他们需要下订单。在这方面，菜单，披萨，顾客和订单听起来是不错的资源。让我们从订单开始。
下一步就是分配这些 URL 到资源。有很多的肯能性，但幸运的是 REST 约定给予了一定支持。在一个典型的 REST API ，资源将分配两个 URL 。首先是资源的名称的复数，如 /orders 。第二个是资源名称的复数加一个唯一的标识符指定单个资源，如 /orders/
由于我们选择了资源并分配了 URL ，我们需要决定客户端可以采取什么样的行动执行。根据 REST 的约定，我们可以知道复数端点( /orders ) 用于列出现有的订单和创造新的订单。有一个唯一标识符的端点（ /orders/
总之，我们的 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 ：分离结构到管理模块的过程。