api接口管理平台设计（api数据接口平台）

本篇文章给大家谈谈api接口管理平台设计，以及api数据接口平台对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享api接口管理平台设计的知识，其中也会对api数据接口平台进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、六大接口管理平台，总有一款适合你的！
• 2、API平台化管理所面临的挑战
• 3、API 设计规范

六大接口管理平台，总有一款适合你的！

先聊一聊前端和后端分离的优点。前后端分离优点如下：

其中不可避免的就是定制好接口文档，后端工程师要写好单元测试，推荐使用 chrome 的插件 postman 或 soapui或 jmeter，service 层的测试用例拿 junit 写。
但是这种情况对于接口文档管理很不方便，所以下面就罗列一些互联网公司常用的接口文档管理平台。

Swagger是一个大型的API开发者的工具框架，该框架提出了一个编写OpenAPI的规范（命名为OAS），并且Swagger可以跨整个API生命周期进行开发，从设计和文档到测试和部署。
Swagger框架三核心：

YApi部署流程介绍

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。它可以帮助开发者轻松创建、发布、以及维护API。除此之外，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。特性:

难点：如果需要要执行自动化测试，需要编写脚本。

Eolinker是国内企业级IT研发管理解决方案服务品牌，在线API接口管理服务供应商，致力于满足各行业客户在不同应用环境中对研发管理全生命周期的个性化需求，提供API开发管理（AMS）、开发团队协作、自动化测试、网关（AGW）以及监控（AMT）等服务。
特性：

ShowDoc一个非常适合IT团队的在线API文档、技术文档工具。
随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供API，APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。

项目地址： https://www.showdoc.cc

DOClever是一个可视化接口管理工具 ,可以分析接口结构，校验接口正确性， 围绕接口定义文档，通过一系列自动化工具提升我们的协作效率。
特性：

DOClever官网： http://www.doclever.cn/controller/index/index.html
DOClever GitHub： https://github.com/sx1989827/DOClever

阿里妈妈前端团队出品的开源接口管理工具RAP第二代，RAP通过GUI工具帮助WEB工程师更高效的管理接口文档，同时通过分析接口结构自动生成Mock数据、校验真实接口的正确性，使接口文档成为开发流程中的强依赖。有了结构化的API数据，RAP可以做的更多，而我们可以避免更多重复劳动。基于RAML的接口定义、文档生成、Mock Server完成了定义和使用的分离，通过一套规范完成的接口定义，可以用不同的工具得到适应不同API管理系统的输出，有更多的可能性，同时保持了核心定义不变。RAP较之于RAML，前者更加集中，所有的定义、文档、mock都在同一个服务中完成，并且实时生效，方便快捷，如果只考虑方便易用，RAP是更好的选择，而RAML显得更加繁琐，更适合于公开的接口定义，方便在各个系统之间流转。

github源码地址： https://github.com/thx/rap2-delos

API平台化管理所面临的挑战

在谈API的管理之前，我们首先要弄清楚我们要管理的到底是什么东西，“API”这个术语本身具有二义性，当我们在不同的上下文谈论它的时候，其实是在说不同的东西或者说“API”扮演的不同角色：

上面的说法都没有问题，而且都在API管理的范畴之内，实际上这三种场景指出了API的三个要素：

长期管理API时，中央软件体系结构团队应该重点关注什么？
API管理平台最大的挑战之一是实现“适当级别”的中心化控制，更加困难的点在于随着管理平台的成熟，“适当级别”本身也在发生变化。随着构建与使用API团队数量的增加，各种各样的知识、观点、经验也在不断增加。想要在所有的团队中保持一致是不现实的，有时候并不是他们不想遵守已经发布的准则，而是有自己的不得已之处，比如：他们依赖另一套第三方产品。。。作为API管理平台，必须兼顾诸如此类的复杂场景，在我们给出的准则中尽可能覆盖所有团队的问题领域，要避免消除合理的多样性，比如：

随着API管理规模的增大，最初运行良好的管理策略难以跟上节奏。API平台化管理相比较于维护单一的API产品需要考虑的问题域是完全不同的，平台中的API数量越多，调用量越大，他们之间进行交互的可能性就越大，其中某些交互会因为API的变更产生意外的结果（错误），并且这些错误很可能难以追溯并修复。这就为API平台管理带来了另一项挑战：如何对运行中的API制定并应用合适的标准来减少意外的变更。

随着API管理的规模化，管理和治理工作通常需要从有关API设计和实施的详细建议转变为API生态系统更通用的标准化，使团队能够自由地进行细节上的决策。

俗话书“万事开头难”，在任何软件项目的初期，我们都需要面临一个非常复杂的问题：选择技术栈。因为决策需要考虑的不确定因素实在太多了，比如：技术栈的更迭、项目组成员的技术背景、项目组成员的意愿等。而对这个处于项目早期的过程我们又不应该冒太多的资本风险来进行大量的讨论与研究。

那么工程领域应对此类问题最常用的方法就是“约束”，组织内部通常会选择和支持一部分工具，并为其提供清晰、详细的技术指南。限制选择可以使得团队做事更快，并降低API变更的速度。

但作为API管理“平台”，一个很重要的任务就是明确地感知平台规模的变化，随着新的业务单元与跨时区团队的集成，“多样性”就成为了生态系统中的一大动脉，“平台方”需要根据规模的变化在合适的时间点增加“技术指南”的多样性而非一味的限制。

技术并非API管理的唯一影响因素，在没有平台化之前，每个API的整个生命周期由一个全功能团队进行管理，但随着API程序的规模和范围的增加，构建和维护API所需要的技术数量会显著上升，不可能每个API开发团队都为自己的API单独部署一套监控、报警、流量限制、门户网站、文档网站等“基建类”服务。

这时可能需要成立一个专门的团队来负责设计和构建供其他团队使用的数据中心监控接口，他们会使用特定的工具集来做特定的事情，比如：使用prometheus或者sumologic来做请求、日志等数据的收集。
同时，可能还会有另一个团队专门整合生态系统中的数据资源来满足特定场景的业务，他们也许会采用类似GraphQL的查询工具来专门为手机应用构建数据接口。

除了成立专门的“基建”团队来做特定的“基建”工作之外，转变组织的决策方式也可以是团队管理的另一个突破点。在企业数字化的初期，团队小且经验不太充足，将技术决策集中到一个单独的指导组能够起到立竿见影的效果，他们通常被冠以“架构组”或者“HOT Office”诸如此类的名字。但是随着数字生态系统的扩张且技术面越来越不均匀，技术决策工作集中在较小的范围是有问题的，单独的技术领导团队不可能保持跟进每一个工具、框架与日常工作的细节，更何况对全球化的团队来说还有时区的限制。因此，可以考虑的解决方案是将决策的过程分解为相互独立的“决策元素”：初始化决策——选项清单——作出选择——授权——执行决策——挑战决策，并将这些“决策元素”的决策权分配到组织中的不同层级。

正如领导领域，在API的治理中，如果有明确的范围与规模限制，提供详细的操作指导和过程文档绝对是最有效的，比如：如何设计URL、URL的命名规范、HTTP头中的版本号应该用什么字段等等。

但随着API生态系统的扩张，维护应用于所有团队的单一指导文档是极其困难的，技术的多样性在企业的生态系统中是一种积极的力量，我们应该尝试驾驭它而非回避，这也是为什么治理文档需要从“直接过程指令”转变为通用原则，这种治理文档的演进模式同样适用于UI/UX的通用指南，比如： 尼尔森诺曼集团的 “十大交互设计原则” 。

同时，对于跨国或者大型组织，治理需要从“发布原则”转换到“收集建议”，分布式的组织结构决定了中心化的治理模型并不适用，这一点是符合“康为定律”的。所以总的来说，随着规模的增长，API的治理模型需要从直接建议转为提出通用原则，再到收集和分享公司团队的实践经验。

API 设计规范

设计时通过将请求和响应之间的不同部分隔离来让事情变得简单。保持简单的规则让api接口管理平台设计我们能更关注在一些更大的更困难的问题上。

请求和响应将解决一个特定的资源或集合。使用路径（path）来表明身份api接口管理平台设计，body来传输内容（content）还有头信息（header）来传递元数据（metadata）。查询参数同样可以用来传递头信息的内容，但头信息是首选，因为api接口管理平台设计他们更灵活、更能传达不同的信息。

所有的访问API行为，都需要用TLS通过安全连接来访问。没有必要搞清或解释什么情况需要TLS 什么情况不需要TLS，直接强制任何访问都要通过 TLS。

理想状态下，通过拒绝所有非TLS请求，不响应http或80端口的请求以避免任何不安全的数据交换。如果现实情况中无法这样做，可以返回403 Forbidden响应。

把非TLS的请求重定向(Redirect)至TLS连接是不明智的，这种含混/不好的客户端行为不会带来明显好处。依赖于重定向的客户端访问不仅会导致双倍的服务器负载，还会使 TLS 加密失去意义，因为在首次非TLS调用时，敏感信息就已经暴露出去了。

制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以，最好在设计之初就使用一些方法来预防可能会遇到的问题。

为了避免API的变动导致用户使用中产生意外结果或调用失败，最好强制要求所有访问都需要指定版本号。请避免提供默认版本号，一旦提供，日后想要修改它会相当困难。

最适合放置版本号的位置是头信息(HTTP Headers)，在 Accept 段中使用自定义类型(contenttype)与其他元数据(metadata)一起提交。例如:

在所有返回的响应中包含ETag头信息，用来标识资源的版本。这让用户对资源进行缓存处理成为可能，在后续的访问请求中把If-None-Match头信息设置为之前得到的ETag值，就可以侦测到已缓存的资源是否需要更新。

为每一个请求响应包含一个Request-Id头，并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值，它能为我们提供一种机制来跟踪、诊断和调试请求。

一个大的响应应该通过多个请求使用Range头信息来拆分，并指定如何取得。详细的请求和响应的头信息（header），状态码(status code)，范围(limit)，排序(ordering)和迭代(iteration)等，参考 Heroku PlatformAPI discussion of Ranges .

在 PUT/PATCH/POST 请求的正文（request bodies）中使用JSON格式数据，而不是使用form 表单形式的数据。这与我们使用JSON格式返回请求相对应，例如:

资源名 （Resource names）:使用复数形式为资源命名，除非这个资源在系统中是单例的 (例如，在大多数系统中，给定的用户帐户只有一个)。 这种方式保持了特定资源的统一性。

行为 （Actions）:好的末尾不需要为资源指定特殊的行为，但在特殊情况下，为某些资源指定行为却是必要的。为了描述清楚，在行为前加上一个标准的actions：

例如：

为了和域名命名规则保持一致，使用小写字母并用 - 分割路径名字，例如:

属性也使用小写字母，但是属性名要用下划线 _ 分割，以便在Javascript****中省略引号。例如：

在某些情况下，让用户提供ID去定位资源是不方便的。例如，一个用户想取得他在Heroku平台app信息，但是这个app的唯一标识是UUID。这种情况下，你应该支持接口通过名字和ID都能访问，例如:

不要只接受使用名字而放弃了使用id。

在一些有父路径/子路径嵌套关系的资源数据模块中，路径可能有非常深的嵌套关系，例如:

推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中，dyno属于app，app属于org可以表示为：

为每一次的响应返回合适的HTTP状态码。好的响应应该使用如下的状态码:

200: GET请求成功，及DELETE或PATCH同步请求完成，或者PUT同步更新一个已存在的资源;

201: POST同步请求完成，或者PUT同步创建一个新的资源;

202: POST，PUT，DELETE，或PATCH请求接收，将被异步处理;

206: GET 请求成功，但是只返回一部分;

使用身份认证（authentication）和授权（authorization）错误码时需要注意：

401 Unauthorized: 用户未认证，请求失败;

403 Forbidden: 用户无权限访问该资源，请求失败;

当用户请求错误时，提供合适的状态码可以提供额外的信息：

422 Unprocessable Entity: 请求被服务器正确解析，但是包含无效字段;

429 Too Many Requests: 因为访问频繁，你已经被限制访问，稍后重试;

500 Internal Server Error: 服务器错误，确认状态并报告问题.

对于用户错误和服务器错误情况状态码，参考： ** **HTTP response code spec

提供全部可显现的资源表述 (例如：这个对象的所有属性) ，当响应码为200或是201时返回所有可用资源，包含 PUT/PATCH和 DELETE 请求，例如:

当请求状态码为202时，不返回所有可用资源，例如：

在默认情况给每一个资源一个id属性。除非有更好的理由，否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识，尤其是自动增长的id。

生成小写的UUID格式 8-4-4-4-12，例如：

为资源提供默认的创建时间 created_at 和更新时间 updated_at，例如:

有些资源不需要使用时间戳那么就忽略这两个字段。

仅接受和返回UTC格式的时间。ISO8601格式的数据，例如:

使用嵌套对象序列化外键关联，例如:

而不是像这样:

这种方式尽可能的把相关联的资源信息内联在一起，而不用改变资源的结构，或者引入更多的顶层字段，例如:

响应错误的时，生成统一的、结构化的错误信息。包含一个机器可读的错误 id，一个人类可读的错误信息（message），根据情况可以添加一个url来告诉客户端关于这个错误的更多信息以及如何去解决它，例如:

文档化错误信息格式，以及客户端可能遇到的错误信息id。

客户端的访问速度限制可以维护服务器的良好状态，保证为其他客户端请求提供高性的服务。你可以使用 token bucket algorithm 技术量化请求限制。

为每一个带有RateLimit-Remaining响应头的请求，返回预留的请求tokens。

请求中多余的空格会增加响应大小，而且现在很多的HTTP客户端都会自己输出可读格式（"prettify"）的JSON。所以最好保证响应JSON最小化，例如：

而不是这样：

你可以提供可选的方式为客户端提供更详细可读的响应，使用查询参数（例如：?pretty=true）或者通过Accept头信息参数（例如：Accept:application/vnd.heroku+json;version=3; indent=4;）。

提供一个机器可读的模式来恰当的表现你的API。使用 prmd 管理你的模式，并且确保用prmd verify验证是有效的。

提供人类可读的文档让客户端开发人员可以理解你的API。

如果你用prmd创建了一个概要并且按上述要求描述，你可以为所有节点很容易的使用prmd doc生成Markdown文档。

除了节点信息，提供一个API概述信息:

提供可执行的示例让用户可以直接在终端里面看到API的调用情况，最大程度的让这些示例可以简单的使用，以减少用户尝试使用API的工作量。例如:

如果你使用 prmd 生成Markdown文档，每个节点都会自动获取一些示例。

描述您的API的稳定性或是它在各种各样节点环境中的完备性和稳定性，例如：加上原型版（prototype）/开发版（development）/产品版（production）等标记。

更多关于可能的稳定性和改变管理的方式，查看 ** **Heroku API compatibility policy

一旦你的API宣布产品正式版本及稳定版本时，不要在当前API版本中做一些不兼容的改变。如果你需要，请创建一个新的版本的API。

关于api接口管理平台设计和api数据接口平台的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 api接口管理平台设计的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于api数据接口平台、api接口管理平台设计的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。