REST API：是什么、HTTP方法及在移动应用中的工作原理

什么是REST API？

REST API（Representational State Transfer API）— 是Roy Fielding在2000年的博士论文中提出的一种架构风格。它定义了一组设计网络协议的限制和原则。符合这些限制的API被称为RESTful。REST不是协议或标准 — 它是一种架构方法，利用现有协议（主要是HTTP）在客户端和服务器之间进行数据交换。

REST的关键理念是 资源导向架构。与在服务器上调用方法（如SOAP或RPC）不同，客户端操作资源：获取其列表、创建新资源、更新或删除。每个资源都是域中的实体：用户、订单、产品、文章。资源有一个状态，以标准化格式（通常为JSON）传递给客户端。服务器不在请求之间存储客户端状态 — 这是stateless原则，REST的关键要求。

REST API的主要特点：

• Stateless — 客户端的每个请求包含处理它所需的所有信息
• Cacheable — 服务器响应必须明确标记为可缓存或不可缓存
• Layered system — 架构可包含中间服务器、负载均衡器、代理服务器
• Uniform interface — 通过HTTP方法、URL和状态码统一的交互接口

REST架构的原则

REST 基于Fielding提出的六个架构限制。遵守这些限制可保证可扩展性、性能和易于集成。每个原则解决分布式系统的特定问题 — 从缓存需求到安全要求。让我们详细看看每个原则。

Uniform Interface原则还包括四个子限制：通过URI标识资源、通过表示操纵资源、自描述消息和HATEOAS（超媒体作为应用状态引擎）。最后一个子限制在实践中常被忽略 — 多数现代REST API并没有完全实现HATEOAS，这导致了关于这种API是否是“真正”RESTful的争论。

Stateless原则 — 对于扩展最重要的原则之一。服务器上没有会话意味着任何服务器实例都可以处理任何请求。这简化了水平扩展：只需在负载均衡器后添加新服务器即可。对于移动应用，stateless还意味着请求可以发送到任何CDN服务器，这对于全球可用性至关重要。

REST中的HTTP方法

REST API中的每个 HTTP方法 对应资源上的特定操作：GET用于读取，POST用于创建，PUT用于完全更新，PATCH用于部分更新，DELETE用于删除。方法的幂等性是关键特征：GET、PUT、DELETE是幂等的（重复执行产生相同结果），POST和PATCH不是。这对于处理网络错误很重要，当客户端不知道请求是否到达服务器时。

• GET — 获取资源或资源列表。幂等，不会改变服务器状态
• POST — 创建新资源。非幂等，每次调用创建新资源
• PUT — 完全替换资源。幂等，重复调用不会改变第一次后的状态
• PATCH — 部分更新资源。部分幂等（取决于实现）
• DELETE — 删除资源。幂等，重复删除返回404，而非错误

HTTP状态码是REST API不可分割的一部分。每个码有特定含义：200 OK 成功的GET，201 Created 用于POST，204 No Content 用于无响应体的DELETE，400 Bad Request 数据无效时，401 Unauthorized 缺少认证，404 Not Found 资源不存在时。正确使用状态码使API自我文档化，并简化调试。

数据格式：JSON和其他

JSON（JavaScript Object Notation）— REST API中数据传输的主要格式。它的流行是因为简单、可读性强以及在JavaScript中的原生支持。JSON通过Content-Type: application/json头进行传输。替代方案包括XML（庞大、过时）、YAML（适合配置，少用于API）和Protocol Buffers（二进制，高负载系统高效）。

REST API中JSON对象的结构通常包含 id、type 字段和资源属性。对于集合，使用带有分页元数据的JSON数组。现代REST API遵循JSON:API规范（jsonapi.org）或JSON Schema用于响应验证。使用统一的数据格式可简化客户端库的开发和文档的生成。

用户列表的JSON响应示例：

{
    "data": [
        {
            "id": 1,
            "name": "安娜·彼特罗娃",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

数据传输格式的选择影响移动应用的性能。JSON通过GZIP可压缩70–80%，这使其适合大多数场景。对于大数据量的实时应用（流媒体、游戏），建议转向二进制协议或使用WebSocket结合Protocol Buffers。

REST API请求示例

让我们看看在移动应用端使用 REST API 的实际示例。以一个管理网店订单的API为例。对于每个HTTP方法，显示请求和服务器的预期响应。示例展示了移动开发中使用的典型RESTful API结构。

GET — 获取订单列表

带分页的获取用户所有订单的请求。响应包含订单对象数组和页面导航的元信息。Page和per_page参数通过query string传递。

// 用于REST API的Retrofit接口
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — 创建新订单

通过POST请求创建新订单。服务器返回状态201 Created和在响应体中创建的对象。重要：创建是在集合/api/v1/orders上执行的，而不是在具体资源上 — 这是标准的RESTful模式。

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// 请求体示例
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — 删除订单

删除资源通过在订单的具体URL上使用DELETE方法执行。成功删除返回204 No Content。DELETE的幂等性意味着重复请求同一URL将返回404 Not Found，客户端可以正确处理这种情况。

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// 在ViewModel中使用
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

这些示例展示了在Android端使用 Retrofit 和 Kotlin Coroutines 的REST API典型实现。对于iOS应用，URLSession或Alamofire库结合Codable协议扮演类似角色。REST API的结构不受平台影响 — 只有执行请求的方式改变。

RESTful API设计：实用建议

设计高质量的 RESTful API 需要遵守使API对开发人员直觉的规约。资源应使用复数名词命名（/users、/orders、/products），HTTP方法应反映操作，URL应显示嵌套结构。错误应返回带有代码和消息的标准化JSON，而不是仅为HTTP状态。遵守这些规约可降低新开发人员的入门门槛，并简化集成。

• 资源命名 — 复数，短横线命名法：/api/v1/user-orders，而非/api/v1/getUserOrders
• 过滤和排序 — 通过query参数：?status=active&sort=created_at:desc
• 分页 — 大量数据用cursor-based，小量用page-based
• 版本管理 — 通过URL（/api/v2/）或Accept-Version头
• 错误 — 统一格式：{ "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — X-RateLimit-Remaining和Retry-After头

设计 REST API 时的常见错误之一是过度嵌套资源。替代/users/1/orders/5/items/3的更好方法是使用平面结构配合query参数：/items?order_id=5&user_id=1。这简化了缓存，不需要服务器支持长路径，且更容易文档化。平面架构在未来迁移到GraphQL时也更好地兼容基于图的查询。

REST API的安全性通过 认证（JWT、OAuth 2.0）和 授权 在资源层级上实现。每个请求都应检查用户是否有权限访问所请求的资源。HTTPS是必须的 — 没有加密，令牌和数据将以明文传输。对于移动应用，建议使用带PKCE（Proof Key for Code Exchange）的OAuth 2.0来安全获取令牌。

版本管理和缓存

版本管理 REST API是为了在变更时保持向后兼容性。最常见的方法：URL中的版本（/api/v1/orders）、头中的版本（Accept: application/vnd.myapi.v1+json）和query参数中的版本（?api_version=1）。URL版本管理是最流行的方法，因为它在日志和文档中清晰可见。但它违反了REST关于资源独一URL的原则。

REST API中的 缓存 通过HTTP头Cache-Control、ETag和Last-Modified实现。标记为可缓存的GET请求可以从浏览器或代理的缓存中服务，无需访问服务器。对于移动应用，缓存尤为重要 — 它减少数据流量消耗，并在网络不佳时加快之前加载数据的显示。ETag是响应内容的散列值：客户端在If-None-Match中发送它，如果数据未变更，服务器返回304 Not Modified。

REST API的现代替代方案包括 GraphQL（客户端灵活选择数据）和 gRPC（基于HTTP/2的二进制协议，适合微服务）。但REST凭借其简单性、普遍性和广泛的工具支持，仍然是公共API的主要标准。REST和替代方案的选择取决于项目的具体要求：请求复杂度、数据量、实时更新需求。