如何提升 API-First 设计流程

本文涉及的产品
NLP 自学习平台,3个模型定制额度 1个月
NLP自然语言处理_高级版,每接口累计50万次
NLP自然语言处理_基础版,每接口每天50万次
简介: 一个 API-First 设计应该具有可复用性、互操作性、可修改性、用户友好性、安全性、高效性、务实性,并且重要的是,与组织目标保持一致。这些基本特征将确保 API 能够有效地为 API- First 组织战略和开发模式做出贡献,在这种模式中,API 可以最大限度地为业务创造价值。但如何生成这样的 API-First 设计呢?

一个 API-First 设计应该具有可复用性、互操作性、可修改性、用户友好性、安全性、高效性、务实性,并且重要的是,与组织目标保持一致。这些基本特征将确保 API 能够有效地为 API- First 组织战略和开发模式做出贡献,在这种模式中,API 可以最大限度地为业务创造价值。

但如何生成这样的 API-First 设计呢?

在本文中,我们将探讨如何通过以下五个流程集成到 API 设计过程中来实现 API-First 设计:

  • 使用自然语言来分析和应对需求
  • 观察上下文并确定约束条件
  • 充分描述和记录 API
  • 利用现有的 API 和指南
  • 将自动化和人工反馈循环集成到流程中


1. 使用自然语言来分析和应对需求

为了确保创建的 API 符合组织的目标,需要使用自然语言深入分析需求。这种分析可能涉及明确消费者或最终用户、他们的用例以及如何实现它们,这对于确定满足需求所必需的每个 API 功能至关重要。进行分析后,应与利益相关者交流预期,以确保一致性。

在进行此类分析时,只能使用自然语言,不考虑编程接口表示,通过这样区分问题将有助于与专家讨论,并避免过早地就诸如/customers or /customerPUT or POST之类的问题展开辩论。最终,你可能会意识到有比标准 REST API 更好的选择,例如,gRPC、异步或 GraphQL API 可能更适合。


2. 观察上下文并确定约束条件

API 设计者和利益相关者必须观察 API 上下文,并确定所有约束条件以确保 API 设计实用、高效且安全。这可能涉及到以下问题:

  • 新 API 应该在什么时候部署?

  • 底层系统是否存在限制?

  • 主题内容是否符合我们创建 API 的常用方法?

  • 安全要求是什么?

接下来,API 设计者和利益相关者可以决定是隐藏还是将约束条件融入设计中。隐藏它们可能会带来额外的工作,但设计更好。另一方面,将它们纳入其中可能会降低 API 的质量,但更容易按期交付。然而,请务必记住安全性是一个不可妥协的问题。


3. 全面描述和编写 API 文档

在设计过程中写好 API 文档至关重要,以确保捕获所有信息,如编程接口描述、需求及其分析、约束和安全要求。这也可以指导你创建合适的 API。

为了描述和记录 API,你可以轻松地使用诸如 OpenAPI、AsyncAPI、GraphQL schema 或 JSON Schema 等 API 规范。这些规范将为你提供一个框架,但它们只能用于记录 API 的元素,而不是消费者如何组合它们以实现在需求分析期间确定的用例。

无论你使用哪种格式,把需求分析和生成 API 连接起来至关重要,以确保最终设计中不会遗漏任何内容。同时还需要向实施者提供尽可能多的信息,确保实现符合预期,例如,在 OpenAPI 文档中, 你可以通过查看摘要来确认在需求分析过程中确定“搜索客户”的操作已转换成 GET /customers 。此外,还可以查看操作安全配置及响应描述,以确保仅返回用户或消费者范围内的客户。


4. 利用现有 API 和指南简化决策过程

API 设计过程涉及到大量的决策。然而许多决策是相同的,因为所有的 API 最终都要处理相同的基本问题,例如,表示日期或金额的最佳方式、如何搜索目录、创建资源或启动流程等。此外,在一个组织内部,所有 API 必须具有共同的样式。

为了避免在漫长且重复性高的讨论中浪费时间或重新设计轮子,可以参考组织内其他 API 并复制它们的设计模式。不过,在描述常见“配方”,如“如何设计搜索操作”或者“如何管理文件上传”的指南中,更高效的方法是将这些模式形式化。API 指南可以涵盖各种主题, 从用户友好性到安全性, 但它们只作用于促进创建 API-First 设计。如果某个指导原则规定对实现该目标没有帮助,就删除它。

遵循指南能够快速实现具有一定用户友好性、互操作性、可扩展能力、安全性和效率的 API 设计,但最重要的是可以帮助你专注于核心问题,创建正确的 API,而不会浪费时间和精力在遣词造句问题上。


5. 将反馈循环整合到流程中

即使指南涵盖了所有相关主题,并以友好的方式呈现,但总有一些 API 设计者可能永远不会看,其他相关的人可能会通过反复检查指南中的细节而减缓进程。此外,任何人在编程接口设计中都可能犯一些小错误。因此,尽早寻求同事、专家和消费者的迭代反馈至关重要,与他们共享扩展的 API 文档以及模拟数据,确保他们能获取到所需的信息,以提供建设性的有效反馈。


Eolink 就是一个 API-first 的优秀案例,设计和开发了一系列的 API 工具平台,包括 API 快速生产、研发管理、自动化测试、网关、监控、开放平台等,实现对 API 的全生命周期覆盖。首创提出 DTDD(文档与测试驱动开发 )理念,通过标准化的工具和流程来解决 API 迭代效率的问题,致力于让 API 管理更简单。

DTDD 文档与测试驱动开发 ):

文档驱动开发:项目开发前,先把文档写好,明确功能需求、入参出参定义、异常情况处理等,再进行开发。

测试驱动开发:项目开发前,先写好测试方案/用例,要求代码顺利通过测试,如不通过则持续进行改进。

DTDD 逻辑图.png

相关文章
|
7月前
|
存储 SQL API
milvus insert api流程源码分析
milvus insert api流程源码分析
277 3
|
3月前
|
缓存 测试技术 API
API的封装步骤流程
API封装流程是一个系统化的过程,旨在将内部功能转化为可复用的接口供外部调用。流程包括明确需求、设计接口、选择技术和工具、编写代码、测试、文档编写及部署维护。具体步骤为确定业务功能、数据来源;设计URL、请求方式、参数及响应格式;选择开发语言、框架和数据库技术;实现数据连接、业务逻辑、错误处理;进行功能、性能测试;编写详细文档;部署并持续维护。通过这些步骤,确保API稳定可靠,提高性能。
|
4月前
|
缓存 前端开发 中间件
[go 面试] 前端请求到后端API的中间件流程解析
[go 面试] 前端请求到后端API的中间件流程解析
|
2月前
|
存储 数据可视化 API
API接口数据获取流程的细化
本文概述了API的基础知识、获取API访问权限的方法、编写代码调用API的步骤、数据处理与分析技巧以及数据安全与合规的重要性,并提供了社交媒体数据分析、天气预报应用和电商数据分析等API数据获取的应用实例,旨在帮助读者全面了解和实践API接口数据获取的流程。
|
1月前
|
存储 监控 安全
API接口数据获取全流程用户指南
本文介绍了从明确需求到数据存储与管理的API接口数据获取全流程。首先,明确业务需求和选择合适的数据源;接着,准备API接口,包括审查文档、申请密钥和安全存储;然后,构建与发送请求,处理响应与数据;最后,进行数据存储与管理,并持续监控与优化,确保数据的安全与合规。通过这些步骤,用户可以高效地获取和管理数据,为数据分析和业务优化提供支持。
|
2月前
|
JSON JavaScript API
商品详情数据接口解析返回的JSON数据(API接口整套流程)
商品详情数据接口解析返回的JSON数据是API接口使用中的一个重要环节,它涉及从发送请求到接收并处理响应的整个流程。以下是一个完整的API接口使用流程,包括如何解析返回的JSON数据:
|
4月前
|
监控 测试技术 API
|
4月前
|
UED 开发工具 iOS开发
Uno Platform大揭秘:如何在你的跨平台应用中,巧妙融入第三方库与服务,一键解锁无限可能,让应用功能飙升,用户体验爆棚!
【8月更文挑战第31天】Uno Platform 让开发者能用同一代码库打造 Windows、iOS、Android、macOS 甚至 Web 的多彩应用。本文介绍如何在 Uno Platform 中集成第三方库和服务,如 Mapbox 或 Google Maps 的 .NET SDK,以增强应用功能并提升用户体验。通过 NuGet 安装所需库,并在 XAML 页面中添加相应控件,即可实现地图等功能。尽管 Uno 平台减少了平台差异,但仍需关注版本兼容性和性能问题,确保应用在多平台上表现一致。掌握正确方法,让跨平台应用更出色。
58 0
|
4月前
|
数据采集 API 数据处理
Onebound万邦API接口采集流程如下(商品详情API接口系列)
Onebound万邦电商API接口采集平台是一个提供商品详情API接口等电商数据采集服务的平台。该平台可以一键抓取多个主流电商平台的商品信息,如淘宝、天猫、京东、1688等,并已经接入了全球多个电商平台的API接口数据,为国内外企业客户提供高质量的电商服务。
|
4月前
|
分布式计算 DataWorks 安全
DataWorks产品使用合集之如何通过API终止运行的流程
DataWorks作为一站式的数据开发与治理平台,提供了从数据采集、清洗、开发、调度、服务化、质量监控到安全管理的全套解决方案,帮助企业构建高效、规范、安全的大数据处理体系。以下是对DataWorks产品使用合集的概述,涵盖数据处理的各个环节。