Nimrita Koul 博士
https://medium.com/@nimritakoul01/application-programming-interface-api-simply-explained-3680d4649121

• 图 1：客户端使用其 API 与服务器交互。应用程序编程接口是应用程序的编程接口 应用程序编程接口 （API）

一、说明

API是应用程序在以编程方式与其他应用程序交互时需要遵循的一组规则。API 代表应用程序编程接口。在 API 上下文中，“应用程序”一词指的是具有独特功能的任何软件。接口可以被认为是两个应用程序之间的服务契约。该合约定义了两者如何使用请求和响应相互通信。

二、API 的类型

允许硬件与软件交互的硬件 API，例如，手机的相机与操作系统交互。

软件 API，允许您从现有软件包或库中调用方法。

允许您通过 Internet 从远程计算机访问资源（数据）或服务（功能）的 Web API。

您可以拥有私有、公共或合作伙伴 API。公共 API 可供任何人使用，合作伙伴 API 仅可供受信任方使用，私有 API 仅限于内部使用。

在本教程中，我们将重点介绍公共 Web API。

二、示例健身应用程序

假设您正在构建一个健身应用程序，并希望显示一张地图，其中突出显示了城市中的所有公园，以便客户可以在其中慢跑。现在，您可以从头开始在您的应用程序中开发此功能，但这不是您应用程序的核心功能，Google 地图专注于此类功能。因此，您将请求 Google 地图应用程序为您提供有关客户城市中公园位置的数据及其创建突出显示这些位置的地图的功能。这样，您就可以专注于健身应用程序的核心功能，同时仍然为您的客户提供额外的功能。

要成功请求 Google Maps 获取所需的数据和所需的功能，您的应用程序必须以 Google Maps API 要求它遵循的特定格式（API 规范）构建请求。

这很像在编程语言中调用函数。您需要根据函数定义的原型构建函数调用，否则会出现错误。

三、可乐自动售货机

有时，自动售货机的类比会有所帮助：

图片来源学分：https://coin-a-drink.co.uk/blog/merchant-media/
自动售货机是一个复杂的系统，具有许多内部系统和细节。为了让客户轻松使用它，它有一个简单的用户界面，带有按钮和一个显示屏，允许客户查看可用物品、选择他们想要的东西、付款、取回零钱和产品。

要成功地将产品从机器中取出，您需要以正确的顺序遵循一组正确的步骤。

这个简单的外部界面使客户能够专注于他们需要的自动售货机产品，而不必担心不必要的细节，它允许自动售货机制造商对客户保密他们的内部细节。

Amazon.com

我们都用过 amazon.com。它的核心功能是为您提供多种产品和选择，让您浏览和选择您想要的产品，将它们放入购物车并购买。为了管理支付部分，amazon.com 使用 PayPal 或 UPI 等第三方的功能，如 Google Pay、PayTM。amazon.com 调用这些支付公司的 API，客户在其中输入他们的身份验证信息、付款并被重定向到 amazon.com 以完成购买和跟踪或订单。

四、客户端和服务器

需要服务 （功能） 或资源 （数据） 的应用程序 （例如，浏览器、python 程序等） 称为客户端。提供所需服务或资源的另一个应用程序称为服务器。（见图 1）。例如，您使用 Google Chrome 客户端访问 amazon.com 提供的服务。

要访问服务或资源，客户端需要按照 API 指定的格式构造请求，并使用 HTTP 等协议将其发送到服务器。服务器根据 API 规范以响应进行响应。

五、超文本传输协议 （HTTP）

处理从客户端到服务器的请求以及通过 WEB 将包含资源表示形式从服务器传输到客户端的响应的协议是 HTTP（超文本传输协议）。因此，HTTP 是一种请求-响应协议。

API 告诉客户端如何形成其请求，以及当它向服务器的端点发出特定请求/调用时会发生什么类型的响应。

5.1 端点

Endpoint 使用一个公开的 uri（统一资源指示器），服务器在该 uri 上公开它提供的资源。

要访问这些资源，客户端必须将其请求定向到此终端节点。

5.2 API 调用

API 调用是从客户端到服务器的 API 端点的请求。

HTTP 为客户端和服务器交互提供了以下方法：

GET — 当客户端想要从服务器读取资源时，它使用 GET 请求。GET 方法是幂等的，即它可以被多次调用，它是安全的（不会删除或更改服务器的内容），它是可缓存的（GET 方法的响应可以由客户端和服务器之间的中间设备缓存，如代理、网关）
POST — POST 方法可以在服务器上创建新资源。PUT 方法请求将包含的实体存储在提供的 Request-URI 下。如果请求 URI 引用已存在的资源，则应将包含的实体视为驻留在源服务器上的实体的修改版本。如果请求 URI 不指向现有资源，并且该 URI 能够由请求用户代理定义为新资源，则源服务器可以使用该 URI （RFC5789） 创建资源。
PUT - 更新资源。它是幂等的。不安全或不可缓存。
PATCH - PUT 的轻量级选项，用于将部分修改应用于资源。PATCH 方法请求将请求实体中描述的一组更改应用于由 Request-URI（统一资源标识符）标识的资源。它不是幂等的。
DELETE- 删除资源，不安全或可缓存。

5.3 HTTP 标头

标头是 HTTP 请求和 HTTP 响应中的附加信息。这些标头可能包含客户端的身份验证凭据、内容类型、响应可以缓存多长时间等信息。如果 HTTP 标头中的控制数据允许压缩信号，则可以在将响应发送到 clinet 之前对其进行 GZIP 压缩。

5.4 有效载荷

Payload 是客户端请求的 HTTP 响应的一部分。它包含所请求资源的表示形式。

突出的 API 架构

• REST（再现状态传输）（RESTful API）
• GraphQL-
  WebSockets
• webhook-
  SOAP（简单对象访问协议）
• gRPC（Google 远程过程调用）
• MQTT（MQ 遥测传输）

RESTful API
今天，大多数 Web API 都是 RESTful API。这意味着它们遵循 REST （REpresentational State Transfer） 原则。它是一种无状态架构，使用 HTTP 方法执行 CRUD（创建、读取、更新、删除）操作。它是 Web 应用程序最常用的 API 架构。

API 需要遵循以下 REST 原则才能被归类为 RESTful API：

它必须处理文档、图像、视频、URL 等资源。
服务器返回的响应将包含以预定格式（如 JSON、XML、HTML 等）表示请求的资源。应用程序状态和功能将被定向到具有唯一标识符 （URI） 的资源中，这些标识符也可用于超媒体链接。
除了以上两条规则外，RESTful API 还需要遵守以下 6 个约束：
从客户端到服务器的请求将使用标准 HTTP 方法（GET、POST、PUT、PATCH、DELETE）进行
请求是无状态的，每个请求都必须有足够的信息供服务器处理请求。无状态允许通过不同的网关和代理路由请求，从而避免引入瓶颈并允许根据需要添加更多中介。
API 遵循客户端-服务器架构（无对等节点）
来自服务器的响应是可缓存的。缓存通过提供来自缓存内容的响应来减少发送到服务器的实际请求数，从而缩短了响应时间并提高了可扩展性。
API 遵循分层系统。客户端和服务器之间的连接有许多 HTTP 中介，如路由器、调制解调器、代理和网关。这些中介可以在 request — response path 的不同点添加，而无需更改组件之间的接口，它们可以在这些接口中执行传递消息的操作（例如缓存它们或翻译它们）。使用网关允许根据方法、URI、内容类型或来自请求的任何其他标头在大量服务器之间分配流量。
API 允许按需编写代码。也就是说，服务器能够将代码加载到客户端并在客户端执行它。Code on Demand 允许将计算移动到更靠近客户端或更靠近服务器的位置，具体取决于可以最快完成工作的位置。
XML-RPC 和 ATOM 发布协议是 RESTful API 的示例。

GraphQL 中：是 API 的一种查询语言，通过允许客户端请求特定数据来提供灵活性。

WebSockets 的 URL：是一个 API，可在通信各方之间提供全双工通信通道，从而在客户端和服务器之间实现实时数据交换

Webhook （网络钩子）：服务器向客户端应用程序发送的通知，由特定事件触发。

SOAP （Simple Object Access Protocol） （简单对象访问协议）：用于结构化数据交换的基于 XML 的协议，通常用于企业环境。

gRPC 中：使用 Protocol Buffers 实现高效数据序列化的高性能、与语言无关的框架。

MQTT（MQ 遥测传输）：适用于 IoT 设备和受限环境的轻量级发布-订阅协议。

API 文档
API 文档规定了 API 的使用规则。它包含有关 API 的以下信息：

1. 身份验证说明 — 如何连接 API
   2.API 端点
   3.终端节点
   的可用资源 4.API
   5 的 HTTP 请求格式。API 服务器返回
   的 HTTP 响应的响应格式 6.响应中包含的响应代码。

5.6 常见 API 状态代码

对于客户端发送到 Web 服务器的每个请求，它都会收到一个状态代码，指示请求发生的情况。与 GET 请求相关的一些常见代码包括：

200：一切正常，结果（如果有）已返回。
301：服务器正在将您重定向到其他终端节点。
400：一个错误的请求。这是客户端错误。即，您可能发送了不正确的数据或错误地调用了 API。
401：身份验证错误。您可能未在对 API 的请求中包含您的登录凭证（如果 API 要求）
403：禁止使用的资源。您无权查看资源。
404：在服务器上的指定位置找不到资源。
503：服务器尚未准备好处理请求。
使用 Python 调用 Web API
您可以使用 Python 请求库进行 API 调用并接收来自服务器的响应。在下面的代码中，我使用 requests 库向 Google Books API 发送 API 调用，以获取与“Python 编程”主题相关的 Google Books 列表。您将需要安装 requests 库。Google Books API 是免费的。

!pip install requests

import requests

def search_books(query):
    """Searches for books based on a query."""
    url = f"https://www.googleapis.com/books/v1/volumes?q={query}"
    response = requests.get(url)
    return response.json()

# Example usage
query = "python programming"
results = search_books(query)

# Print the titles of the first few books
for item in results['items']:
    print(item['volumeInfo']['title'])

Output:
Python Programming
Introduction to Python Programming
Learning Python
Taming PYTHON By Programming
Bite-Size Python
LEARN PYTHON WITH 200 PROGRAMS
Python for Kids, 2nd Edition
Python Programming For Beginners
An Introduction to Python Programming: A Practical Approach
Python Tutorial

• Postman邮差

Postman 是一个平台，用于构建您自己的 API 并轻松使用其他人提供的 API。

• cURL

cURL 是一个命令行工具和库，用于使用 URL 传输数据，即向服务器发出 HTTP 请求和接收响应。

5.8 设计 API 的最佳实践

设计：在 API 设计中优先考虑简单性、一致性和可理解性。
文档：全面、清晰和最新的文档对于 API 的成功至关重要。
版本控制：实施明确的版本控制策略来管理 API 更改，而不会中断现有客户端。
错误处理：提供信息丰富的错误消息以及明确的解决方法指导。
安全：使用适当的身份验证和授权机制保护 API 端点。
性能：优化 API 响应以提高速度和效率，以增强用户体验。
速率限制：实施速率限制以防止滥用并确保公平使用。
缓存：利用缓存提高性能并减少服务器负载。
测试：在部署之前严格测试 API 以识别和修复问题。
监测：持续监控 API 性能和使用情况，以进行优化和故障排除。
开发人员体验：专注于通过出色的文档、支持和工具创造积极的开发人员体验。