前言

在现代互联网系统中，REST API（Representational State Transfer Application Programming Interface）无处不在，是系统组件之间进行通信和数据交换的事实标准。无论是前后端、服务间、微服务还是移动端，REST API 都是最常见的通信接口形式。

定义

Wiki 定义如下：

A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.

简而言之：

REST API 是一种遵循 REST 架构风格、基于 HTTP 协议的接口标准。

工作原理

一句话： REST API 通过标准化的 HTTP 方法对资源进行操作，并使用统一的 URI 定位资源。

核心原则包括：

  • 每个资源通过 URI 唯一标识
  • 使用 HTTP 方法进行操作（GET, POST, PUT, DELETE 等）
  • 无状态（每次请求都应包含足够信息）
  • 使用标准的数据格式（如 JSON、XML）

属性与指标

设计与使用 REST API 时常关注以下属性与性能指标：

  1. 资源粒度与 URI 设计 语义化、可读性强，如 /users/{id}/orders

  2. HTTP 方法语义

    • GET：读取资源
    • POST：创建资源
    • PUT：更新资源（幂等）
    • DELETE：删除资源

  3. 状态码语义

    • 200 OK、201 Created、204 No Content
    • 400 Bad Request、404 Not Found、500 Internal Server Error 等

  4. 性能指标

    • 延迟（Latency）
    • 吞吐量（QPS）
    • 可用性（Availability）
    • API 成功率（Success Rate）

  5. 安全性

    • 身份验证（如 OAuth2）
    • 授权（Scope）
    • 加密（HTTPS）

  6. 版本控制

    • 如 /v1/users，或通过 HTTP Header 管理版本

  7. 幂等性

    • 除了 POST，其他操作应尽量幂等（即重复操作不影响结果）

类型

按照资源操作风格分类

  1. 纯 RESTful API 严格遵循 REST 规范，语义清晰，便于缓存和文档化。

  2. REST-like API 接口形式像 REST，但未完全遵循 HTTP 方法语义。

  3. RPC 风格的 API 接口更像函数调用，常见于 gRPC、JSON-RPC。

按照调用方式分类

  1. 同步 REST API 直接返回响应，是最常见的形式。

  2. 异步 REST API 响应仅包含任务 ID，后续需轮询或回调通知。

REST API 与程序关系

REST API 是连接前后端、微服务、外部集成的桥梁：

  • 前端通过 REST API 获取数据进行渲染
  • 移动端通过 REST API 与服务器通信
  • 微服务之间通过 REST 实现解耦调用
  • 第三方系统通过 API 接入核心服务

设计良好的 API 能极大提升团队协作效率与系统可扩展性。

常用 REST API 工具/框架

工具/框架 说明
Postman API 调试和文档平台
Swagger / OpenAPI 接口规范定义与文档自动生成
FastAPI Python 高性能 API 框架
Spring Boot Java 中最常用的 REST 构建框架
Express.js Node.js 的轻量 REST API 框架
Kong / Apigee API 网关，用于认证、限流、监控

总结

REST API 是现代系统开发的基石，它通过标准化的协议和简洁的设计，降低了系统间集成的成本。理解并掌握 REST API 的设计原则、方法语义和性能指标，是每一个开发者的必修课。

记住一句话：好 API 就像好 UI，一眼就能明白它的用法。