搜索
首页后端开发php教程[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 :分离结构到管理模块的过程。
声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
您什么时候使用特质与PHP中的抽象类或接口?您什么时候使用特质与PHP中的抽象类或接口?Apr 10, 2025 am 09:39 AM

在PHP中,trait适用于需要方法复用但不适合使用继承的情况。1)trait允许在类中复用方法,避免多重继承复杂性。2)使用trait时需注意方法冲突,可通过insteadof和as关键字解决。3)应避免过度使用trait,保持其单一职责,以优化性能和提高代码可维护性。

什么是依赖性注入容器(DIC),为什么在PHP中使用一个?什么是依赖性注入容器(DIC),为什么在PHP中使用一个?Apr 10, 2025 am 09:38 AM

依赖注入容器(DIC)是一种管理和提供对象依赖关系的工具,用于PHP项目中。DIC的主要好处包括:1.解耦,使组件独立,代码易维护和测试;2.灵活性,易替换或修改依赖关系;3.可测试性,方便注入mock对象进行单元测试。

与常规PHP阵列相比,解释SPL SplfixedArray及其性能特征。与常规PHP阵列相比,解释SPL SplfixedArray及其性能特征。Apr 10, 2025 am 09:37 AM

SplFixedArray在PHP中是一种固定大小的数组,适用于需要高性能和低内存使用量的场景。1)它在创建时需指定大小,避免动态调整带来的开销。2)基于C语言数组,直接操作内存,访问速度快。3)适合大规模数据处理和内存敏感环境,但需谨慎使用,因其大小固定。

PHP如何安全地上载文件?PHP如何安全地上载文件?Apr 10, 2025 am 09:37 AM

PHP通过$\_FILES变量处理文件上传,确保安全性的方法包括:1.检查上传错误,2.验证文件类型和大小,3.防止文件覆盖,4.移动文件到永久存储位置。

什么是无效的合并操作员(??)和无效分配运算符(?? =)?什么是无效的合并操作员(??)和无效分配运算符(?? =)?Apr 10, 2025 am 09:33 AM

JavaScript中处理空值可以使用NullCoalescingOperator(??)和NullCoalescingAssignmentOperator(??=)。1.??返回第一个非null或非undefined的操作数。2.??=将变量赋值为右操作数的值,但前提是该变量为null或undefined。这些操作符简化了代码逻辑,提高了可读性和性能。

什么是内容安全策略(CSP)标头,为什么重要?什么是内容安全策略(CSP)标头,为什么重要?Apr 09, 2025 am 12:10 AM

CSP重要因为它能防范XSS攻击和限制资源加载,提升网站安全性。1.CSP是HTTP响应头的一部分,通过严格策略限制恶意行为。2.基本用法是只允许从同源加载资源。3.高级用法可设置更细粒度的策略,如允许特定域名加载脚本和样式。4.使用Content-Security-Policy-Report-Only头部可调试和优化CSP策略。

什么是HTTP请求方法(获取,发布,放置,删除等),何时应该使用?什么是HTTP请求方法(获取,发布,放置,删除等),何时应该使用?Apr 09, 2025 am 12:09 AM

HTTP请求方法包括GET、POST、PUT和DELETE,分别用于获取、提交、更新和删除资源。1.GET方法用于获取资源,适用于读取操作。2.POST方法用于提交数据,常用于创建新资源。3.PUT方法用于更新资源,适用于完整更新。4.DELETE方法用于删除资源,适用于删除操作。

什么是HTTP,为什么对Web应用程序至关重要?什么是HTTP,为什么对Web应用程序至关重要?Apr 09, 2025 am 12:08 AM

HTTPS是一种在HTTP基础上增加安全层的协议,主要通过加密数据保护用户隐私和数据安全。其工作原理包括TLS握手、证书验证和加密通信。实现HTTPS时需注意证书管理、性能影响和混合内容问题。

See all articles

热AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover

AI Clothes Remover

用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool

Undress AI Tool

免费脱衣服图片

Clothoff.io

Clothoff.io

AI脱衣机

AI Hentai Generator

AI Hentai Generator

免费生成ai无尽的。

热门文章

R.E.P.O.能量晶体解释及其做什么(黄色晶体)
3 周前By尊渡假赌尊渡假赌尊渡假赌
R.E.P.O.最佳图形设置
3 周前By尊渡假赌尊渡假赌尊渡假赌
R.E.P.O.如果您听不到任何人,如何修复音频
3 周前By尊渡假赌尊渡假赌尊渡假赌
WWE 2K25:如何解锁Myrise中的所有内容
3 周前By尊渡假赌尊渡假赌尊渡假赌

热工具

mPDF

mPDF

mPDF是一个PHP库,可以从UTF-8编码的HTML生成PDF文件。原作者Ian Back编写mPDF以从他的网站上“即时”输出PDF文件,并处理不同的语言。与原始脚本如HTML2FPDF相比,它的速度较慢,并且在使用Unicode字体时生成的文件较大,但支持CSS样式等,并进行了大量增强。支持几乎所有语言,包括RTL(阿拉伯语和希伯来语)和CJK(中日韩)。支持嵌套的块级元素(如P、DIV),

SublimeText3 Linux新版

SublimeText3 Linux新版

SublimeText3 Linux最新版

螳螂BT

螳螂BT

Mantis是一个易于部署的基于Web的缺陷跟踪工具,用于帮助产品缺陷跟踪。它需要PHP、MySQL和一个Web服务器。请查看我们的演示和托管服务。

SublimeText3汉化版

SublimeText3汉化版

中文版,非常好用

安全考试浏览器

安全考试浏览器

Safe Exam Browser是一个安全的浏览器环境,用于安全地进行在线考试。该软件将任何计算机变成一个安全的工作站。它控制对任何实用工具的访问,并防止学生使用未经授权的资源。