🚀 你需要知道的一切，才能用 Rails 构建你的第一个 RESTful API

如今，万物互联，API（应用程序编程接口）已成为实现不同应用程序之间通信和数据交换的基本方面。

目录

 1.什么是API？
 2.什么是RESTful API？

       2.1. RESTful API 的核心原则

       2.2设计您的 RESTful API

       2.3.实现您的 RESTful API：

       2.4构建自定义 RESTful API 的最佳实践
 3.使用 Rails 构建 RESTful API

       3.5.设置你的 Rails 项目

       3.6.确定资源和路线

       3.7.在 Rails API 中实现控制器操作

       3.8.在 Rails API 中序列化数据

       3.9测试您的 RESTful API
 4.参考资料

什么是API？

API，即应用程序编程接口，充当两个软件应用程序之间的中间人，允许它们相互通信和交换数据。它定义了一组规则和规范，规定了这些应用程序如何交互。

假设你有两个不同的应用程序：一个是菜谱应用，一个是生鲜配送应用。菜谱应用本身不具备直接从超市订购食材的功能。但是，如果菜谱应用有一个可以连接到生鲜配送应用API的接口，那么它就可以共享你的购物清单，让你直接通过菜谱应用订购食材。

API是程序吗？

• API 本身并不是程序：它们是一组指令和规范，软件应用程序遵循这些指令和规范进行通信。
• API 可用于各种用途：它们可用于共享数据、访问其他应用程序的功能，甚至可用于触发其他应用程序中的操作。

什么是 RESTful API？

RESTful API被认为是构建 API 最高效、可扩展的方法，它们遵循表述性状态转移 (REST) 的核心原则。在这种范式中，API 被设计用来表示一个资源，用户可以通过 API 提供的表示形式来操作该资源。RESTful API 还遵循 HTTP 协议，这使得它们对开发者来说更​​易于访问和集成。

RESTful API 的核心原则

• 客户端-服务器架构： REST 将客户端（使用 API 的应用程序）和服务器（提供 API 的应用程序）的职责分离。客户端向服务器发出请求，服务器则返回相关数据。
• 无状态通信：客户端向服务器发出的每个请求都应包含处理该请求所需的所有信息，使服务器独立于之前的请求。
• 基于资源的 API： API 的设计围绕资源展开，这些资源代表用户、产品或订单等数据实体。每个资源都有一个唯一的标识符（URI），并且可以使用标准的 HTTP 方法进行操作。
• 标准HTTP方法： RESTful API利用标准HTTP方法进行CRUD（创建、读取、更新、删除）操作：
  • GET：检索资源。
  • POST：创建新资源。
  • PUT：更新现有资源。
  • 删除：删除资源。

设计您的 RESTful API

1. 确定资源：定义系统中的核心实体及其关系。
2. 选择资源名称：对资源使用描述性复数名词（例如/users，，/products）。
3. 定义端点：将 HTTP 方法映射到资源上的特定操作。
   • 使用 GET 获取资源（/users/{id}）或集合（/users）。
   • 使用 POST 创建新资源（/users）。
   • 使用 PUT 更新现有资源（/users/{id}）。
   • 使用 DELETE 删除资源（/users/{id}）。
4. 版本控制：实施版本控制以管理 API 变更并确保向后兼容性。
5. 错误处理：使用标准 HTTP 状态代码（例如，404 - 未找到，400 - 错误请求）返回清晰且信息丰富的错误消息。

设置您的 RESTful API：

• 选择框架： Ruby on Rails、Django（Python）和 Spring Boot（Java）等流行框架提供了构建 RESTful API 的内置功能。
• 定义路由：根据 HTTP 方法和资源将 URL 映射到特定的控制器操作。
• 数据序列化：选择一种用于返回数据的格式，通常为 JSON 或 XML，以确保一致性并方便客户端应用程序使用。
• 安全性：实施身份验证和授权机制，以保护您的 API 免受未经授权的访问。

构建 RESTful API 的最佳实践

• 使用描述性强且一致的资源名称。
• 遵循标准的HTTP方法和状态码。
• 清晰地记录您的 API。
• 验证并清理用户输入，以防止安全漏洞。
• 实施缓存机制以提高性能。
• 对于大型数据集，可以考虑使用分页。
• 使用自动化测试工具对您的 API 进行全面测试。

使用 Rails 构建 RESTful API

如何使用 Ruby on Rails 构建 RESTful API

使用 Ruby on Rails 构建 RESTful API 可以充分利用该框架的优势，简化 API 开发中的常见任务。以下是使用 Ruby on Rails 创建健壮且可扩展 API 的分步指南：

设置你的 Rails 项目

• 首先使用以下--api标志创建一个新的 Rails 应用程序：

rails new my_api --api

此标志专门针对 API 开发配置您的应用程序，排除不适用于 Web 应用程序的功能。

在 Ruby on Rails 中定义 API 的资源和路由

• 使用 Rails 的 Active Record 来识别和建模您的资源。
• 例如，创建一个名为 `model` 的模型，User其属性类似于name`and` email。

rails generate model User name:string email:string

• 使用命令为每个资源生成一个控制器rails generate controller。

rails generate controller Users

• 在文件中定义路由config/routes.rb，将 HTTP 方法映射到控制器操作。

resources :users, only: [:index, :create]

GET这样，您可以通过向同一端点发送请求来检索所有用户，也可以通过向同一端点发送请求来/users创建新用户。您还可以类似地为其他操作（例如更新和删除用户）定义路由。POST

在 Rails API 中实现控制器操作

• 每个控制器操作都对应一个特定的 HTTP 方法，并处理请求逻辑。
• 例如，该index操作UsersController会获取所有用户并以 JSON 格式返回它们：

class UsersController < ApplicationController
  def index
    @users = User.all
    render json: @users
  end
end

• 同样，该create操作会接受请求正文中的用户数据并创建一个新用户：

def create
  @user = User.new(user_params)
  if @user.save
    render json: @user, status: :created
  else
    render json: @user.errors, status: :unprocessable_entity
  end
end

private

def user_params
  params.require(:user).permit(:name, :email)
end

在 Rails API 中序列化数据

• Rails 默认使用该render json:方法自动将数据序列化为 JSON。
• 您可以使用库来自定义序列化过程，Active Model Serializers以便更好地控制数据结构。

在哪里测试你的 RESTful API

• 使用诸如Postman或之类的工具curl向您的 API 端点发送请求并验证其功能。
• 编写单元测试和集成测试，以确保您的 API 行为符合预期。

本文内容简单易懂，是一篇面向初学者的文章，旨在指导您了解如何使用 Ruby on Rails 构建 RESTful API。

参考

Rails 官方指南
图片：什么是 API？
图片：什么是 RESTful API？
如何构建 RESTful API：使用 Ruby on Rails 增强您的开发能力
封面图片
创建 Rails 7 REST API
使用 Swagger 正确地编写 Rails API 文档