如何设计 API：基本指南 + 最佳实践

如何设计 API：基本指南 + 最佳实践

引用

CSDN

1.

https://blog.csdn.net/qq_30621637/article/details/142684588

概述

系统接口是不同组件、子系统或系统之间的交互和交换点。它们对于任何系统工程项目的功能、性能和可靠性都是必不可少的。然而，在数字生态系统中，软件解决方案的指数级增长凸显了API在实现无缝集成方面的关键作用。如何设计API带来了常见的挑战，设计系统接口并不是一项简单的任务。它需要仔细考虑系统生命周期中所有利益相关者的需求、期望和约束。在本文中，您将学习为所有利益相关者设计系统接口的最佳实践和方法。

步骤

步骤一：定义目的，涉众和需求范围

设计系统接口的第一步是确定谁是利益相关者即谁调用/使用接口，以及他们接口要求是什么。每个利益相关者可能对系统接口有不同或冲突的要求因此，与所有利益相关者进行沟通并以清晰，一致的方式沟通，分析，验证和记录其要求。

明确定义其目的和范围确保API为其预期用户提供特定的、有价值的功能然而，在深入技术细节之前，开发人员必须提出关键问题来确定API的目标，包括

1. 谁是 API 的主要利益相关者？
   系统有利益或影响的任何人，如客户、用户、开发人员、测试人员、操作员、维护人员、监管机构和供应商
2. API 将解决哪些具体问题？
3. API如何与现有系统（如复合API）集成？
4. 用户与API交互的预期结果是什么？
5. 是否有任何需要考虑的具体约束或要求
   功能、可用性、安全性、可靠性、兼容性、可维护性、可扩展性和敏感数据的安全性

这些问题有助于您轻松地了解如何设计API的后续步骤，防止功能蠕变，并确保API保持可管理性和相关性。例如，如果API需要与复合API一起工作，那么了解它将如何从各种源获取、合并和操作数据是至关重要的。这种规划的远见使开发阶段更加顺利，解决问题的策略更加有效。

步骤二：研究和规划API端点规范

设计系统接口的下一步是定义描述系统接口端点的特征和行为的接口规范。接口规范是指定系统接口的输入、输出、数据类型、格式、协议、标准、规则和约束的正式文档。它们还定义了系统接口的验证及确认方法和标准。接口规范应该与系统需求和体系结构一致，并且应该由所有涉众一致同意。在整个系统生命周期中，它们还应该是可跟踪的、可测试的和可管理的。

以下是在仔细研究和规划API规范需要考虑的事项：

1. 理解API的目的：明确定义API的目标。这种理解对于使端点与API的目标保持一致至关重要
2. 定义端点：为API公开的每个函数或资源创建相应的端点。这些端点是用户与API交互的访问点，因此它们必须具有逻辑性和可预测性。
3. 设计直观的路径：每个端点应该有一个直观的路径，表明其功能。这种清晰度增强了可用性和开发人员的经验
4. 指定访问方式和资源：详细说明每个端点将支持的操作（GET、POST、PUT、DELETE），确保它们符合RESTful设计的原则或API遵循的特定协议。
5. 合并复合 API 策略：在规划端点时，考虑使用复合 API 来简化复杂的交互和数据检索过程，提高效率和性能。

💡

复合API策略主要涉及到在现有系统基础上添加API层，同时利用敏捷设计策略，根据业务需求灵活调整和优化API设计。这种策略结合了绿地策略和螺旋策略的特点，旨在充分利用现有代码和系统，同时保持设计的灵活性。具体来说，复合API策略包括以下几点

如何设计API的过程需要一种深思熟虑的方法来规划和构建端点。您可以通过清晰的目标、直观的命名、精确的行动资源映射和复合API的战略使用，创建一个强大的、用户友好的API。请记住，API的成功在于开发人员在应用程序中如何理解、采用和利用它。

步骤三： 从安全设计开始

在设计API时，从一开始就强调安全至关重要。API的体系结构应结合强大的安全功能，以保护未经授权的访问和数据泄露。随着开发人员踏上这个关键阶段，几个重要的考虑因素必须指导其方法：

1. 实施身份验证和授权：选择可靠的机制（例如OAuth或API密钥）来验证用户身份并控制访问级别。
2. 速率限制：为了防止滥用并确保公平访问，限制用户在给定时间范围内的请求频率
3. 数据加密：使用HTTPS加密传输中的数据，保护敏感信息免受拦截。
4. 遵守法规：了解并遵守与您的用户相关的数据保护法律，确保您的API符合全球标准。

设计以安全性为核心的 API 的关键是在风险成为问题之前预测并减轻风险。通过将安全措施嵌入到 API 的设计中，开发人员可以创建一个更具弹性和更值得信赖的平台。这增强了 API 的可靠性并建立了用户信任，这是长期成功的关键因素。

本文原文来自CSDN