课程介绍

本课程的目标

本课程面向希望快速掌握如何设计和构建 Web API 的软件开发人员和设计师。由于课程内容基于多年实践积累的培训材料，因此如果你需要为团队或公司自行组织 API 培训课程，本课程将非常实用。

课程结构

本课程分为五个章节：“入门”、“设计阶段”、“构建阶段”、“发布阶段”以及“附录”。每一章涵盖一组关键技能，从理解 API 概念到最终将 API 部署至生产环境。以下是各章节的简要概述：

入门

第一章为理解 API 世界奠定基础。首先介绍“以 API 为中心”的设计理念及其在 API 开发中的意义。接着了解我们将使用的现有服务背景，以及实现 API 的整体计划。在第二章中，我们将深入探讨创建 API 所常用的协议与实践，包括 HTTP 协议以及基于 HTTP 的 REST 风格服务。

设计阶段

本阶段聚焦于 API 的建模、设计与描述过程。我们将学习使用工具对 API 进行建模和可视化，并生成可被机器读取的 API 描述文件，这些文件可用于后续生成最终的 API 接口。

构建阶段

API 开发的构建阶段重点是将设计完善且定义清晰的 API 转化为可运行的代码。我们采用三步法：草图绘制、原型开发，最后完成实际构建。使用 Apiary Blueprint 格式进行草图设计，通过 OpenAPI 规范（也称为 Swagger）定义精确接口，最终利用 Node.js 和一个名为 DARRT 的自定义框架，将 Swagger 规范转化为可执行代码。

发布阶段

在发布阶段，我们将学习如何测试、保护并部署已完成的 API 到云端。具体而言，使用本地 Postman 平台进行测试，借助 Auth0 云服务实现身份验证与访问控制，并将最终的 API 部署到 Heroku 公有云平台。

当确认一切按预期运行后，我们还将探讨如何在不破坏现有 API 使用方的前提下，对生产环境中的 API 进行小幅更新。

线性推进方式

尽管本课程采用从建模、构建到发布的线性结构，但在实际开发中，API 的开发通常涉及大量迭代，需在各个阶段之间反复调整。大多数实际项目中，开发流程是一系列循环：先建模，再设计，然后返回修改模型，继续优化设计，如此往复，直到 API 准备就绪并可发布至云端。

虽然迭代循环是实际工作的正确方式，但对于一门教学课程而言，线性结构更利于知识传递。因此，本课程将保持从始至终的线性讲解方式，同时在过程中不断提醒大家：迭代与循环是设计和构建高质量 API 的核心要素。

本课程涵盖的内容

本课程旨在全面覆盖将一个全新 API 成功部署到生产环境所需的全部流程。我们将重点讲解构建 RESTful API 所需的技能。这类 API 基于 HTTP 协议，采用当前绝大多数 Web API 所通用的请求-响应模式。此外，还有其他重要的 API 风格（如 gRPC 和 GraphQL），但受限于课程范围，无法一一涵盖。值得庆幸的是，大多数其他 API 风格仍建立在基于 HTTP 的 Web API 基础之上，这正是本课程的核心内容。掌握 RESTful API 的原理，将为你今后探索其他 API 风格打下坚实基础。

Web API 是一个广泛的主题，无法在本课程中面面俱到。本课程聚焦于围绕外部接口（即 API）的一系列步骤，用于访问后端服务。但不会涉及如何构建和部署后端服务（有时称为微服务），也不会深入讲解编写调用 Web API 的客户端应用。此外，与 API 管理相关的更广泛主题也不在本课程范围内。

示例项目介绍：BigCo 公司

在本课程中，我们将协助一家虚构企业——BigCo 公司，通过设计、构建并部署一个全新的“入职 API”（Onboarding API），实现其新客户接入流程的现代化改造。目前，该公司的客户入职流程主要依赖人工填写表格，并将数据手动录入多个独立运行的应用系统中。我们的任务是深入了解 BigCo 当前的客户入职流程，将其转化为 API 设计，并基于公司已有的后端服务，实现一个统一的入职 API，自动完成原本由员工操作的各项步骤。

关于 BigCo 公司：Bayesian International Group of Companies（简称 BigCo）是一家虚构企业，用于本课程的示例场景。该公司曾是世纪之交关键技术的制造商，产品包括移动 X 光机和水听器。BigCo 还在推动现代计算机时代多个研究领域的发展中发挥了重要作用，例如预测算法和机器人控制。目前，BigCo 的产品专注于逆概率问题，致力于利用这些技术提升公共与私营部门的决策和政策制定水平。

在整个过程中，我们将学习 API 设计的基本原则，以及如何以一致的方式生成和记录设计文档，确保 BigCo 的入职团队和技术开发人员都能准确理解。我们还将介绍一种简单的三阶段方法（草图、原型、构建），用于将 API 设计转化为可运行代码。代码完成后，我们将完整走一遍发布流程：测试、安全加固和部署上线。最后，我们还将探讨如何在不影响现有调用方的前提下，对已发布的 API 进行更新维护。