API2024-09-25

API 的概念和例子

API (Application Programming Interface), 由一系列命令, 函数和协议组成, 实现不同应用程序间的交互.

主要目的是定义软件组件间交互方法和数据结构.

API 作为链接接收应用的请求, 从服务获取必要的数据, 然后将处理后的数据返回给应用.

API 的类型

  • 公共或开发 API
  • 内部或私有 API
  • 合作 API (不回对公共开发, 专门设计给合作伙伴使用的)

REST APIs

构建网络应用并与之交互的规则, 依靠标准的 HTTP 方法和协议实现客户端与服务器之间的通信.

REST APIs 的原则

  • 无状态: 客户端向服务器发出的每个请求都必须包含所有理解和解析请求的必要信息, 服务端不会存储任何有关客户端的会话状态
  • 客户端-服务端架构: 客户端和服务端通过请求和响应进行交互的独立组件. 客户端处理用户界面和用户体验, 服务端管理数据存储
  • 统一接口: 采用统一的方式访问资源. 包括使用 HTTP 方法 (GET, POST, PUT 和 DELETE 等) 来访问和操作资源
  • 可缓存: 来自服务器的响应被标记为可 / 不可缓存, 可以减少客户端与服务器的交互次数, 提高性能

SOAP APIs

SOAP (Simple Object Access Protocol), 一种在网络应用中交换结构化信息的协议. SOAP 利用 XML 作为信息格式, 结构更为复杂.

SOAP 内置的命令可以确保安全性, 适用于具有严格安全性的应用.

SOAP 和 REST 之间的不同

  • 协议和架构
    • SOAP: 有标准的规则和协议
    • REST: 使用标准 HTTP 方法
  • 信息格式:
    • SOAP: XML
    • REST: JSON, XML, HTML 或纯文本
  • 复杂性:
    • SOAP: 由于自身的标准和 XML 信息会更复杂
    • REST: 简单, 灵活, 更容易实现
  • 通信
    • SOAP: 使用各种协议
    • REST: 通常使用 HTTPs

JSON 和 XML

都是标准的 API 通信数据格式, 目的都是在服务器和客户端之间对数据结构进行编码, 以便双方都可以理解.

JSON

源自于 JavaScript 的轻量级数据交换格式, 便于人类理解, 也便于机器解析和生成

XML

一种标记型语言, 定义了以人类和机器都可读的格式对文档进行编码的结构. XML 以其处理复杂数据结构的能力而著称.

JSON 和 XML 之间的不同

  • 可读性
    • JSON: 可读性更高, 快速交互, 便于开发人员使用
    • XML: 更复杂的语法, 展示复杂数据结构和文档
  • 大小
    • JSON: 更紧凑和轻量, 因此有更快的数据传输更少的带宽占用
    • XML: 更大, 因为使用了 markdown 标签
  • 数据类型
    • JSON: 支持字符串, 数字, 数组和对象
    • XML: 所有文本形式, 需要对特定形式进行解析
  • 解析和性能
    • JSON: 解析更快, 尤其在 JavaScript 环境中
    • XML: 解析慢, 需要更多资源
  • 模式支持
    • JSON: 不如 XML 广泛
    • XML: 在验证文档结构和数据类型方面非常强大

如何使用

下面的情况可以使用 JSON

  • 需要轻量数据格式
  • 与 web APIs 合作, 尤其是 JavaScript 环境
  • 简洁和可读性十分重要
  • 处理简单数据结构并需要降低带宽使用

下面的情况可以使用 XML

  • 处理复杂数据类型结构
  • 需要验证数据格式和结构
  • 使用需要大量元数据和描述性数据的应用
  • 数据交换需要具有高度的可扩展性和自描述性

API 端点

一个 URL, 客户端可通过该 URL 访问 API 以执行操作. 端点代表 API 提供的功能和服务.

端点可以让 API 与正在运行的应用进行交互, 从而实践通信和信息交换, 使用 HTTP 方法进行访问.

HTTP 方法

  • GET
  • POST
  • PUT
  • DELETE

HTTP 状态码

  • 200: 请求成功
  • 400: 数据未正确获取或资源不存在
  • 500: 服务端错误

认证和授权

通常通过 API Keys, OAuth tokens 或用户凭证进行

API keys 和 OAuth

API Keys 是一个唯一标识, 包含在 API 请求中, 用于识别项目或应用, 跟踪和控制 API 的使用方式.

OAuth 是基于令牌的身份验证框架, 允许第三方应用程序在不暴露用户凭证的情况下访问用户数据.

API 安全的重要性

  • 阻止未认证的访问
  • 速率限制
  • 监控

速率限制和节流

使用速率限制保持稳定性和安全性, 限制应用在一定时间内的请求次数

APIs 测试

API 测试工具

  • Postman
  • cURL
  • Swagger

测试 API 的方法

  1. 定义端点和方法
  2. 设置请求信息
  3. 发送请求
  4. 分析响应
  5. 错误处理
  6. 自动测试