RESTful API详解

RESTful API是基于REST架构风格构建的API，其设计遵循REST(Representational State Transfer，表现层状态转移)架构的一组原则和约束条件

RESTful API的核心思想是以资源为中心，通过统一的接口(通常是HTTP协议)进行通信，使客户端和服务器能够实现无状态的交互

资源

在RESTful API中，资源是web服务的核心，所有数据和功能都被视为资源。资源可以是任何事物，例如用户、订单、文件等

资源通过URI(统一资源标识符)来进行唯一标识。URI通常采用路径结构，指向具体的资源，例如

• GET /users获取所有用户资源

• GET /users/123获取 ID 为 123 的具体用户

• POST /users创建新用户

• PUT /users/123更新 ID 为 123 的用户

• DELETE /users/123删除 ID 为 123 的用户

HTTP方法

RESTful API通过标准的HTTP方法操作资源，这些方法代表了不同的操作语义

• GET从服务器获取资源，此操作是只读的，不会改变服务器状态

• POST在服务器创建新资源

• PUT更新资源，可以是替换整个资源或创建资源

• PATCH局部更新资源，只修改资源的某一部分

• DELETE从服务器删除资源

我们举几个例子

• GET /books获取所有书籍

• GET /books/5获取 ID 为 5 的具体书籍

• POST /books创建新书籍

• PUT /books/5更新 ID 为 5 的书籍

• DELETE /books/5删除 ID 为 5 的书籍

HTTP状态码

RESTful API使用HTTP状态码向客户端反馈操作结果。常见的状态码包括

• 200 OK请求成功，返回资源或执行成功

• 201 Created:资源创建成功，通常用于POST操作

• 204 No Content操作成功但不返回内容，常用于DELETE请求

• 400 Bad Request请求无效，客户端发送的数据格式或参数有误

• 401 Unauthorized客户端未授权

• 403 Forbidden客户端无权访问资源

• 404 Not Found请求的资源不存在

• 500 Internal Server Error服务器内部错误

路径设计

RESTful API的路径设计应尽量清晰、简洁，并且语义明确。以下是一些路径设计的最佳实践

• 使用名词表示资源:路径中不应包含动词，操作逻辑由HTTP方法决定

• 使用复数形式表示资源集合:例如，/users代表用户集合，/users/123代表具体用户

• 层次结构:URI 路径应体现资源之间的层次关系，例如:

  • GET /users/123/posts获取用户123的所有帖子

  • GET /users/123/posts/456获取用户123的具体帖子456

无状态性

RESTful API遵循无状态性原则，即服务器不应在不同请求之间存储客户端的状态信息。每个请求都应该是独立的，并且包含处理该请求所需的所有信息，例如身份验证令牌等

这种设计简化了服务器端的实现，提高了系统的可扩展性

使用JSON作为数据格式

虽然RESTful API并不强制使用特定的数据格式，但JSON是目前最流行的选择，因其简洁且易于解析

JSON格式的请求体，创建新用户

{
  "name": "pasiphae",
  "email": "pasiphae321@gmail.com"
}

响应体，获取用户

{
  "id": 123,
  "name": "pasiphae",
  "email": "pasiphae321@gmail.com"
}

缓存

RESTful API 支持缓存机制，以减少服务器负载并提高性能。服务器可以通过HTTP响应头(如Cache-Control)指示客户端是否可以缓存响应

GET请求通常可以通过缓存优化，而POST、PUT、DELETE等请求则不应该缓存

版本控制

API在迭代过程中可能会引入不兼容的变更，因此需要对API进行版本控制。常见的版本控制方式包括

• URI中的版本号:例如/v1/users

• HTTP头中的版本号:例如在Accept头中指定版本号

• 查询参数中的版本号:例如GET /users?version=1

错误处理

当请求失败时，RESTful API应返回明确的错误信息和相应的HTTP状态码，以便客户端理解错误原因，错误信息应包含足够的细节，下面是一个响应体例子

{
  "error": "Bad Request",
  "message": "User ID must be a positive integer."
}

HATEOAS(超媒体即应用状态引擎)

RESTful API的一个可选特性是HATEOAS

它规定服务器应在响应中提供相关资源的链接，以便客户端可以发现和导航 API 的其他部分，HATEOAS使API更加自描述

{
  "id": 123,
  "name": "pasiphae",
  "_links": {
    "self": { "href": "/users/123" },
    "friends": { "href": "/users/123/friends" }
  }
}

安全性

RESTful API的安全性至关重要，特别是在生产环境中。常见的安全措施包括

• HTTPS:所有通信应通过HTTPS进行加密

• 身份验证:通常使用令牌(如 JWT)或OAuth进行用户身份验证

• 权限控制:确保用户仅能访问自己有权访问的资源

分页、排序、过滤

对于大数据集，RESTful API通常需要提供分页、排序和过滤功能

分页通常通过查询参数来实现

• GET /users?page=2&limit=50获取第 2 页，每页 50 个用户

• GET /users?sort=name&order=asc按名称升序排序

• GET /users?role=admin只获取管理员用户

RESTful API设计的关键原则

• 表现层状态转移:客户端通过操作资源的表现层(通常是JSON或XML数据)来管理资源的状态

• 统一接口:通过简单、固定的HTTP方法和标准化的资源URI进行操作

• 无状态性:请求独立，服务器不保留会话状态

• 可缓存性:合理设置缓存机制以提高性能

• 分层系统:客户端无需知道服务器的具体实现，可以通过中间层(如负载均衡、缓存代理)提高可扩展性

 

本文参考的文章

表现层状态转移

RESTful API 设计指南

What is a REST API?