首页 > 后端开发 > php教程 > [PHP][API]Chapter 6: API Design

[PHP][API]Chapter 6: API Design

WBOY
发布: 2016-06-20 12:30:04
原创
901 人浏览过

本章节标志一个转折点在我们了解 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 :分离结构到管理模块的过程。
来源:php.cn
本站声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
热门教程
更多>
最新下载
更多>
网站特效
网站源码
网站素材
前端模板