掌握RESTful API生命周期管理：从设计到维护的全面指南

应用程序编程接口（API）的设计自计算机早期时期就已存在——不久之后，程序员意识到一组明确定义的方法或函数有助于促进编程的交流。尽管不同 API 的规格各异，但最终目标是通过利用 API 提供的服务，为程序员带来价值。

与软件工程的许多其他方面一样，托管生命周期有助于促进 API 的开发。由于外部 API 使用者的影响，API 生命周期管理需要最高程度的管理，而 API 开发人员可能未必意识到这一点。这是因为使用该 API 的开发人员必须依赖于在他们的洞察力或控制范围之外做出的决策。

API 的种类繁多，从专有例程到基于既定标准的例程应有尽有。本文档将重点介绍 RESTful API 生命周期管理。

什么是 API？

根据 TechTerms.com 的定义，应用程序编程接口（API）是“程序员可以用来创建软件或与外部系统交互的一组命令、函数、协议和对象。它为开发人员提供了执行常见操作的标准命令，因此无需从头开始编写代码。”

虽然 API 使用的概念在信息技术（IT）领域已经存在了几十年，但它在基于 Web 的服务中得到了推动。这些服务最初通过基于 SOAP的协议发展起来，为 RESTful 对应物铺平了道路，而 RESTful 在过去五到七年中成为 API 发展的主要推动力。

什么是RESTful API？

RESTful API（Representational State Transfer API）是一种基于HTTP协议的轻量级架构风格，用于设计网络应用程序。它遵循REST（表述性状态转移）原则，使得API的使用更加直观和易于理解。以下是RESTful API的一些关键特性：

1. 无状态：每个请求从客户端到服务器都包含所有必要的信息，服务器不需要保存会话信息。
2. 资源导向：API中的数据和操作被视为资源，通常以URI（统一资源标识符）的形式表示。
3. 统一接口：API应该有一个统一的接口，使得不同的系统之间可以更容易地交互。
4. 可缓存：数据应该被标记为可缓存或不可缓存，这有助于提高性能。
5. 分层系统：客户端通常不知道它们是直接与服务器通信还是通过中间层（如代理服务器）。
6. 按需代码（可选）：服务器可以传输执行代码到客户端，客户端可以执行这些代码来增强其功能。
7. 超媒体作为应用状态的引擎（HATEOAS）：API应该提供足够的信息，使得用户可以发现API中的其他资源，这是通过超链接实现的。

RESTful API通常使用HTTP方法（如GET、POST、PUT、DELETE等）来执行不同的操作，这些方法对应于资源的CRUD（创建、读取、更新、删除）操作。例如：

• GET：用于获取资源。
• POST：用于创建新资源。
• PUT：用于更新现有资源。
• DELETE：用于删除资源。

RESTful API的设计使得它们易于使用，并且可以轻松地与其他系统集成。

如何区分 SOAP 和 REST？

从基于 Web 的服务角度来看，SOAP（简单对象访问协议）和 REST（表述性状态转移）是开发人员面临的两个主要选择。理解它们的区别至关重要。

在制定有关 API 开发的架构和设计决策时，了解 REST 和 SOAP之间的优缺点和差异至关重要。可以同时支持 REST 和 SOAP 的 API 产品通常是首选方法，这取决于客户的需求。

接口模型：RESTful 服务的四个约束

RESTful 服务使用一个统一的接口来解耦架构，并分为以下四个约束。

资源识别

资源使用统一资源标识符（URI）进行命名。这些资源与返回给客户端的结果不同。考虑以下 GET 请求：

http://dzone.com/products

这个虚构的请求将包含 fakelibrary.org 域提供的产品列表，可能使用 JSON 格式：

[

    {

        "id": 1,

        "name": "Product One"

    }, 

    {

        "id": 2,

        "name": "Product Two"

    },

    {

        "id": 3,

        "name": "Product Three"

    }

]

使用 REST，以下 GET 示例可用于从产品列表中返回特定资源：

http://dzone.com/products/2

此 URI 将返回 ID 等于 2 的产品：

{

    "id": 2,

    "name": "Product Two"

}

通过表示操纵资源

在客户端表示资源时，如果调用者具有适当的权限，则可以进行修改和删除。使用上面的示例，可以构造以下 JSON 数据：

{

    "id": 2,

    "name": "Product Two Updated"

}

并作为 PUT 请求的正文传递给以下 URI：

http://dzone.com/products/2

如果 PUT 请求成功，则 ID=2 的产品名称将从“Product Two”更改为“Product Two Updated”。

自我描述性消息

作为 REST 消息的一部分，指定了 Internet 媒体类型（以前称为 MIME 类型），以便可以调用正确的解析器。常见的 Internet 媒体类型是“application/json”。

超媒体作为应用程序状态的引擎（HATEOAS）

RESTful 客户端在访问 URI 路径时，能够发现所需的所有可用操作和资源，从而避免了信息硬编码的需要。

接口协议

RESTful 服务契约可以分为以下四个区域：

• 请求：处理发送到 RESTful 服务器的入站请求。
• 响应：封装从服务器返回给客户端的信息。
• 路径：请求资源的唯一标识符。
• 参数：请求中包含的元素，用于过滤或指定请求中使用的键值对。

什么是RESTful API 安全？

RESTful 应用程序依赖于 API 生态系统的底层安全性，而不是在 REST 架构样式中直接包含安全性。除了使用 HTTPS 协议保护 RESTful API 调用外，还应使用基于会话的身份验证。目前，大多数 RESTful 应用程序都利用 OAuth 2.0 和 OpenID Connect（OIDC）协议。

• SAML
  安全评估标记语言（SAML）最初由大学设计，旨在向其他大学的学生授予对库的访问权限。SAML 是基于 XML 和 SOAP 构建的原始联合身份系统，推出于 2000 年代初期，当时 Internet 浏览器是主要客户端。
• OAuth 2
  OAuth 2 创建于 2006 年，是一种开放标准的身份验证协议，通过 HTTP 提供授权工作流，使用访问令牌而非凭据对设备、服务器、应用程序和 API 进行授权。OAuth 因 Facebook、Google、Microsoft 和 Twitter 的使用而广受欢迎，这些平台允许将账户使用权与第三方应用程序或网站共享。
• OpenID Connect（OIDC）
  OpenID Connect 扩展了 OAuth 2，并将用户信息（身份层）作为请求的一部分包含在内。OIDC 被认为是 SAML 的现代版本，允许多种客户端，包括基于 Web 的客户端、移动设备客户端和使用 JavaScript 的客户端。
• JSON Web 令牌（JWT）
  JSON Web 令牌（JWT）是一种开放标准，用于创建包含声明的访问令牌。这些令牌用 JSON 编写，设计紧凑，专门用于 Web 浏览器和单点登录（SSO）上下文。虽然 JWT 不是身份提供商或服务提供商，但它用于在身份提供商和服务提供商之间传递经过身份验证的用户身份。

什么是RESTful API 建模语言（RAML）？

RESTful API 建模语言（RAML）是一种用于描述 RESTful API 的语言。RAML 使用 YAML 这种人类可读的数据序列化语言编写。自 2013 年首次提出以来，RAML 得到了 MuleSoft、AngularJS、Intuit、Box、PayPal、可编程 Web 和 API Web Science、Kin Lane、SOA Software 和 Cisco 等技术领导者的支持。RAML 的目标是提供描述 RESTful API 所需的所有信息，从而简化 API 设计过程。

以下是一个由 MuleSoft 提供的 Notes 示例 API 的 RAML 文件示例：

#%RAML 0.8

title: Notes Example API

version: v2

mediaType: application/json

documentation:

  - title: Overview

    content: This is an example of a simple API for a "notes" service

/notes:

  description: A collection of notes

  get:

    description: List all notes, optionally filtered by a query string

    queryParameters:

      q:

        description: An optional search query to filter the results

        example: shopping

    responses:

      200:

        body:

          example: |

            [ { "id": 1, "title": "Buy some milk", "status": "done" },

              { "id": 2, "title": "Return sweater", "status": "overdue", "dueInDays": -2 },

              { "id": 3, "title": "Renew license", "status": "not done", "dueInDays": 1 },

              { "id": 4, "title": "Join gym", "status": "not done", "dueInDays": 3 } ]

  post:

    description: Create a new note in the collection

    body:

      example: |

        { "title": "Return sweater", "dueInDays": -2 }

    headers:

      X-Tracking-Example:

        description: You can specify request headers like this

        enum: [ accounting, payroll, finance ]

        required: false

        example: accounting

    responses:

      201:

        headers:

          X-Powered-By:

            description: You can describe response headers like this

            example: RAML

        body:

          example: |

            {

              "id": 2,

              "title": "Return sweater",

              "status": "overdue",

              "dueInDays": -2

            }

  /{id}:

    description: A specific note, identified by its id

    uriParameters:

      id:

        description: The `id` of the specific note

        type: number

        example: 2

    get:

      description: Retrieve the specified note

      responses:

        200:

          body:

            example: |

              {

                "id": 2,

                "title": "Return sweater",

                "status": "overdue",

                "dueInDays": -2

              }

RAML 提供了一个完整的 API 设计生命周期，分为五个阶段：

设计

通过使用易于阅读的 YAML 格式，API 设计变得更加直观。利用专用的 RAML 工具（如 API Workbench 和 API Designer）或 IDE 插件（如 Sublime 和 Visual Studio），可以加快开发速度，减少代码重复，并对 API 进行原型设计和完善。在 RAML 文件中构建 API 构建块后，可以添加模拟数据，以便在编写实际代码之前进行原型设计和测试，从而在开发早期验证 API。

建模

设计完成后，可以开始对 API 逻辑进行实际编程。此时，RAML 文件成为规范，流行语言如 NodeJS、Java、.NET、Mule 和 IOT Noble 等可以简化构建过程。以下是一个基于 Java 和 JAX-RS 框架的 RAML 示例：

@Path("/notes")

public interface NotesExampleResource

{

  @POST

  @Consumes("application/json")

  Response createNote(Note note, @Context UriInfo uriInfo);



  @GET

  @Produces("application/json")

  Notes getNotes(@QueryParam("q") String query);

}

使用 RAML for JAX-RS 框架，Java 接口也可以生成 RAML 文件，这为利用 RAML 规范提供了另一种选择。

测试

在设计和建模阶段之后，API 开发生命周期的下一个逻辑步骤是测试。这些单元测试对于确保 API 保持向后兼容性，并满足当前要求至关重要。Abao、Vigia 和 Postman 等工具允许导入 RAML 规范，创建设置脚本和测试以验证 API。此外，测试服务如 API Fortress、API Science 和 SmartBear 提供了对延迟、响应、有效载荷和错误的测试支持。

文档

API 文档通常是一个挑战，工具如 Swagger 和 Miredot 可能无法提供完整的信息，导致依赖开发人员指定注释和 JavaDocs 等特定于语言的文档。由于 RAML 规范将文档作为核心优先事项，文档与代码保持同步。RAML 规范充当 API 的接口（或合同），与底层业务逻辑同步。API 控制台、RAML 转 HTML 和 PHP RAML2HTML 等工具提供了快速简便的方式来公开标准化文档，这些文档可以在公司内部网上保密或供公众使用。

共享

在 API 开发生命周期中的所有构建块都已就位后，最后一个阶段是共享 API。RAML 规范引入了几种集成 API 的方法：

SDK 生成：使用 RAML 文件可以自动构建 Java、.NET、PHP、Ruby、NodeJS、iOS、Windows 和 Go 等语言的软件开发套件（SDK）。

第三方工具：Oracle 和 MuleSoft 将 RAML 功能包含在他们的工具集中，只需粘贴规范即可连接到任何使用 RAML 的 API。

API Notebook：为开发人员提供一个环境，用于测试 API、操作 API 调用的结果，并使用 JavaScript 语言连接到多个 API。

关联关系

JAX-RS 和 RAML 的关联关系在于它们共同支持 RESTful API 的开发生命周期。RAML 专注于 API 的设计和描述，而 JAX-RS 专注于 API 的实现。在实践中，开发者可以先使用 RAML 定义 API 的结构和行为，然后利用 JAX-RS 实现这些定义。这种结合使用可以提高开发效率，确保 API 的一致性和可维护性。

RAML 0.8 与 1.0

RAML 规范 0.8 仍然是当前标准，但版本 1.0 自 2016 年 9 月开始获得支持。版本 1.0 包括以下更新：

• 数据类型：提供统一且高效的方式来对 API 数据进行建模，并支持子架构。
• 示例：允许多个示例并添加注释以促进语义注入。
• 注释：合并经过验证的模式以实现可扩展性。
• 库：改进了模块化，以促进 API 工件的重用。
• 覆盖/扩展：允许使用单独的文件以提高可扩展性。
• 改进的安全架构：增加了对 OAuth 的支持，并引入了基于密钥的架构。

什么是RESTful API 版本控制？

对 RESTful API 进行版本控制一直是一个争论不休的话题，主要围绕版本控制的实施方式。版本控制的三个主要选项是 URI、HTTP 标头和消息架构标识符。

虽然没有正确或错误的答案，但建议设定一个标准并坚持执行，以减少 API 消费者的混淆。

URI

基于 URI 的版本控制方法在 RESTful API 的 URI 中包含版本号。例如，产品 API 的 3.0 版本如下所示：

http://dzone.com/v3.0/products

这种方法最为流行，因为可以清楚地看到正在使用的 API 版本。然而，批评者认为，资源的 URI 不应仅因为 API 版本变化而更改。

HTTP 标头

HTTP 标头方法旨在保持 URI 的干净，并在标头中添加版本信息。产品 API 的 3.0 版本将使用以下通用 URI：

http://dzone.com/products

但 HTTP 标头将包含以下信息：

HTTP GET:

https://dzone.com/products

api-version: 3.0

虽然 URI 始终相同，但批评者认为这种方法不描述资源的语义。

消息架构标识符（内容类型）

与 HTTP 标头选项类似，消息架构标识符（或内容类型）版本控制策略在标头中创建自定义 Internet 内容类型。使用相同的通用 URI：

http://dzone.com/products

标头已更新为反映自定义内容类型：

Accept: application/vnd.dzone.app.products-v3.0+json

虽然 URI 始终相同，但批评者指出版本引用被隐藏，自定义的 Internet 内容类型可能复杂且难以测试。

无版本控制

虽然对公共 API 来说这不是一个选项，但在内部开发 API 并对所有使用者有影响和控制权的情况下，可能会考虑不实施版本控制。这种做法可以避免版本控制和维护多个版本的挑战。

批评者认为，这种方法只是避开了需要解决的版本控制问题。因此，即使是私有 API，也应设计为公开可用的资源，并包括版本控制的需求。

什么是API 生命周期？

API 生命周期的管理包括以下核心方面，每个方面都有其特定的步骤和任务：

设计

设计生命周期与 RAML 开发生命周期相似，重点是 API 的初步构思和设计过程，包括：

• 概念化：初步设计和需求收集阶段，制定 API 的初步构思。在创建 RAML 规范之前，需要进行一定程度的构建以产生模拟/原型结果。
• 模拟/原型：在实际构建 API 之前，使用模拟或原型数据来提供 API 预期的结果，为后续的反馈阶段做准备。
• 反馈：将初步设计结果展示给利益相关者或产品所有者，获取他们的反馈并将其与最初设定的期望进行比较。
• 验证：根据反馈调整 API 设计，确保设计符合需求，并准备进入实施阶段。

实施

实施阶段专注于实际的程序开发和测试，包括：

• 开发：编写实际的程序代码以满足 API 的需求，并进行单元测试和集成测试以确保功能正确。
• 测试和验证：进行质量保证工作，验证 API 服务是否符合预定的验收标准，确保其性能和稳定性。

管理

管理阶段处理 API 的运营、维护和优化，包括：

• 安全：实施 API 保护措施，包括设定访问控制和服务级别选项，进行安全审查和渗透测试以保障 API 的安全性。
• 部署：使用持续交付/持续集成工具（如 Jenkins、Bamboo/Pipelines、GitLab、Travis CI）来部署 API，确保其在生产环境中的顺利运行。
• 监视：通过监控工具跟踪 API 的使用情况，确保其正常运行，并及时发现和解决问题。
• 故障排除：在 API 部署后遇到问题时，利用日志和跟踪系统诊断问题，并进行修复。
• 管理：确保 API 能满足当前和未来的需求，可能需要增加运行实例的数量或扩展托管服务的资源。
• 淘汰：当 API 不再需要或过时时，进行适当的处理。这包括通知依赖于该 API 的系统或用户，并在受监管的环境中执行额外的任务以确保平稳过渡。

RESTful API常见的问题有哪些？

1. 问：什么是RESTful API？
   答：RESTful API 是一种基于HTTP协议的轻量级架构风格，用于设计网络应用程序。它使用标准的HTTP方法如GET、POST、PUT、DELETE等来处理数据。
2. 问：RESTful API有哪些主要特点？
   答：RESTful API的主要特点包括无状态、可缓存、统一接口、分层系统、通过超媒体作为应用状态的引擎（HATEOAS）。
3. 问：为什么RESTful API是无状态的？
   答：RESTful API是无状态的，意味着每个请求从客户端到服务器都必须包含理解请求所需的所有信息，服务器不会存储任何请求之间的信息。
4. 问：什么是HATEOAS？
   答：HATEOAS是“Hypermedia as the Engine of Application State”的缩写，它是一种在RESTful API中使用超媒体链接来指导客户端如何与API交互的机制。
5. 问：RESTful API通常使用哪些HTTP方法？
   答：RESTful API通常使用以下HTTP方法：GET（读取资源）、POST（创建资源）、PUT（更新资源）、DELETE（删除资源）、PATCH（部分更新资源）。
6. 问：如何设计一个好的RESTful API端点？
   答：设计一个好的RESTful API端点应该使用名词而非动词，避免使用CRUD操作的直接映射，并且应该反映出资源的层次结构。
7. 问：什么是API版本控制？
   答：API版本控制是在API的URL中包含版本号的做法，例如 /api/v1/resource，这样可以在不影响旧版本客户端的情况下对API进行更新。
8. 问：RESTful API如何处理错误？
   答：RESTful API通过HTTP状态码来处理错误，例如404表示资源未找到，500表示服务器内部错误。此外，API还可以返回错误信息和错误代码，帮助客户端理解错误原因。
9. 问：什么是API速率限制？
   答：API速率限制是一种安全措施，用于限制客户端在一定时间内可以发起的请求数量，以防止滥用API。
10. 问：什么是API文档，为什么它很重要？
    答：API文档是详细说明API如何使用、包括哪些端点、每个端点的请求和响应格式的文档。它对于开发者理解和使用API至关重要，有助于提高开发效率和保证API的正确使用。

总结

RESTful API 生命周期管理包括三个核心方面：设计、实现和管理。这三个方面涵盖了 API 的整个生命周期，从概念到验证，再到实施和最终弃用。生命周期建立在经过验证的 RESTful API 设计之上，并将简单性包裹在这些概念周围，以确保稳定、安全的实现，并能够根据需要进行扩展。

RAML 的引入有助于在设计阶段标准化元素，使得组织能够更好地构建、交付和记录 API。其架构适应了整个 RESTful API 生命周期管理结构，并使用标准命名法提供了清晰的指导。

原文链接：RESTful API Lifecycle Management