应用API优先的方法意味着设计API时,使其具有一致性和适应性,无论应用于哪些开发项目。对API使用API​​描述语言(如OpenAPI)是关键,因为它有助于建立API与其他程序通信的枢纽,即使这些系统各自的语言不同。当然,API不存在于单独的真空中,因此与其利益相关者的协作和规划对于设计过程同样重要,设计过程早在任何代码实际编写之前就开始了。简而言之,实施API优先的策略需要你在设计流程开始前就已经确定下了。

为什么API优先设计很重要?

传统上,一旦发现问题并且有人意识到新系统能够提供必要的解决方案,软件设计过程就开始了。一旦建立了广泛的草图,下一步通常就会深入挖掘以评估可能需要的任何用例和正在创建的系统所需的交互形式。当然,所有这一切都必须考虑到用户体验(UX),因为拥有一个有效的系统是不够的; 对于即将与之交互的开发人员和使用者而言,它也需要对用户友好,无论是在后端还是在前端。

有时问题甚至更简单,如果你有一个内部应用程序,其中包含你希望通过API访问其他系统的数据。但是,该系统有自己的逻辑,可以告知其行为和与他人的交互方式。因此,你创建的任何API都将围绕这些特性和规则构建。一旦你的内部应用程序作为API连接的一部分,开发人员就会根据系统的内部结构进行交互并附加上它。如果这是你想要的,那可能没问题,但如果你以后需要对你的内部模型进行更改,就会出现问题。使用API​​优先方法进行设计意味着构建一个不仅仅是内部系统副产品的API。

开发人员应该能够快速又轻松地了解API的工作方式,并与其他应用程序集成在一起。只有这样,他们才能编写优雅的代码,以便与其他系统进行有效的交互,标准就是正确运行API时,它既向后兼容又往前扩展。

API优先设计方法的优点

1.开发团队可以并行工作

签订协议允许开发人员同时在API开发的不同阶段工作,而无需等待应用程序更新所需的时间。因此,开发人员可以根据预先建立的计划模拟API并有效地测试任何相关的参数项,这样就会无形中提高了整体的开发效率。

2.降低开发应用程序的成本

API优先设计方法的可重用性允许代码从一个项目转移到另一个项目,以便开发团队始终拥有可以使用的基线架构。通过消除每次都要从头开始编码的需要,任何相关的时间和财务成本也同样降低。此外,开发人员能够更快速地解决API问题,而且无需新建任何代码,从而可以更顺畅地与其他应用程序集成。

3.加快发布速度

自动化支持的“可直观查看”API使新手开发人员能够快速轻松地与API文档进行交互。实际上,许多API构建过程可以使用具有可视API编辑器的工具自动化,可以导入API定义文件并自动生成文档,甚至模拟API的返回结果。这些工具大大缩短了开发时间,提高了产品发布的速度。

最重要的是,使用API​​优先的方法,你仍然可以灵活地添加新的应用程序产品功能,而无需重新设计API体系结构。这是敏捷开发的环境管理的一个明显优势,因此预计应用程序更新将根据最终用户需求快速发布。

4.改善开发者体验

开发人员每天都与API进行交互,因此创建一个提供积极的开发人员体验(DX)的API至关重要。API第一种设计方法产生的API经过精心设计,并且具有良好的文档记录并且与其核心保持一致。开发人员可以使用API​​更轻松地与其他应用程序集成,快速解决出现的任何问题,甚至可以在更短的时间内登陆其他开发人员,这要归功于不那么强大的学习曲线。

5.降低失败风险

对于大多数企业而言,API是开发环境中不可或缺的一部分,涉及从营销和销售到代表其品牌的、面向使用者的应用程序等所有内容。任何部分的API故障都可能是毁灭性的。但是,采用API设计优先的方法,由于设计和实现的固有的可靠性,稳定性和一致性,大大降低了出错的可能性。

应用集成环境下的API设计

API为系统之间的通信提供了统一的结构,无论是新的还是传统的,允许数据传输进行转换。但API实施不仅仅是一个IT问题,必须根据整个组织的目标设计API。通过将API策略置于设计流程的最前面,可以改进系统之间的应用程序集成和互操作性,并在许多情况下进行优化。而且如果更改,你仍然可以选择用其他方式进行开发。

精心设计的API有什么特点?

最有效的API设计包括以下属性:

1.易于阅读和使用:详细全面且简洁的API文档易于阅读,并提供支持开发人员使用的简单示例。引用和参数都非常直观,因此易于学习和记忆。

2.难以滥用:实现和集成API方式很容易区分,使开发人员很难滥用它,即使在编写代码时也是如此。它还包含信息反馈,同时允许开发人员具有相当程度的灵活性。

3.完整而简洁: API非常全面,允许开发人员使用其通信的数据,在可预见的未来,逐步构建完整的应用程序。这种稳定可用性和灵活性代表了每个API创建者应该追求的设计理念的类型。

API优先设计的工具

现在,有很多许多工具和标准可以支持API优先开发,如EOLINKER、RAML、Swagger,都提供了出色的编辑工具来支持API优先设计的策略。EOLINKER主要在文档页面清晰,编辑逻辑简易,支持自定义MOCK测试,而且支持UI直观化的自动化测试,读取代码注释生成文档也可以胜任,而Raml和Swagger页面显示也不错,可以编辑、测试等基本功能,不过相比EOLINKER,在自动化测试功能方面略显不足,而且只有前者是支持中文的,后两种只支持英文语言。这些API编辑器都能轻松地实现API版本的控制,使得更容易在更短的时间内完成整个开发测试流程。

附上EOLINKER的官方网址:https://www.eolinker.com

附上Swagger的官方网址:https://swagger.io/

附上RAML的官方网址:https://raml.org/

最后的想法

API优先的方法可以对API的使用产生巨大的影响。如果你设计的API目标包括高使用率和保留率,或者提供给开发人员出色的开发体验,那更是如此。最有效的API设计通过易于理解的内容和明确的目标导向提供直接的使用者体验,从而实现快速集成和使用。同样,随着学习曲线的降低,API才会享受其可重用性和让开发人员的持续参与。


参考资料:David Brown,Implementing an API-First Design Methodology

原文地址:https://dzone.com/articles/implementing-an-api-first-design-methodology

实现API优先设计的重要性和实现方式的更多相关文章

  1. 优秀的API接口设计原则及方法(转)

    一旦API发生变化,就可能对相关的调用者带来巨大的代价,用户需要排查所有调用的代码,需要调整所有与之相关的部分,这些工作对他们来说都是额外的.如果辛辛苦苦完成这些以后,还发现了相关的bug,那对用户的 ...

  2. 关于API的设计与实现

    http://blog.csdn.net/horkychen/article/details/46612899 API的设计是软件开发中一个独特的领域.最主要的特殊点在于API是供开发者使用的界面,即 ...

  3. RESTful API URI 设计的一些总结

    非常赞的四篇文章: Resource Naming Best Practices for Designing a Pragmatic RESTful API 撰写合格的 REST API JSON 风 ...

  4. RESTful API URI 设计: 查询(Query)和标识(Identify)

    相关文章:RESTful API URI 设计的一些总结. 问题场景:删除一个资源(Resources),URI 该如何设计? 应用示例:删除名称为 iPhone 6 的产品. 是不是感觉很简单呢?根 ...

  5. RESTful API URI 设计: 判断资源是否存在?

    相关的一篇文章:RESTful API URI 设计的一些总结. 问题场景:判断一个资源(Resources)是否存在,URI 该如何设计? 应用示例:判断 id 为 1 用户下,名称为 window ...

  6. Atitit.会员卡(包括银行卡)api的设计

    Atitit.会员卡(包括银行卡)api的设计 1. 银行卡的本质是一种商业机构会员卡1 2. 会员卡号结构组成1 2.1. ●前六位是:发行者标识代码 Issuer Identification N ...

  7. Web API接口设计经验总结

    在Web API接口的开发过程中,我们可能会碰到各种各样的问题,我在前面两篇随笔<Web API应用架构在Winform混合框架中的应用(1)>.<Web API应用架构在Winfo ...

  8. atitit.基于http json api 接口设计 最佳实践 总结o7

    atitit.基于http  json  api 接口设计 最佳实践 总结o7 1. 需求:::服务器and android 端接口通讯 2 2. 接口开发的要点 2 2.1. 普通参数 meth,p ...

  9. paip.复制文件 文件操作 api的设计uapi java python php 最佳实践

    paip.复制文件 文件操作 api的设计uapi java python php 最佳实践 =====uapi   copy() =====java的无,要自己写... ====php   copy ...

  10. 好RESTful API的设计原则

    说在前面,这篇文章是无意中发现的,因为感觉写的很好,所以翻译了一下.由于英文水平有限,难免有出错的地方,请看官理解一下.翻译和校正文章花了我大约2周的业余时间,如有人愿意转载请注明出处,谢谢^_^ P ...

随机推荐

  1. C# Word中设置/更改文本方向

    C# Word中设置/更改文本方向 一般情况下在Word中输入的文字都是横向的,今天给大家分享两种方法来设置/更改一个section内的所有文本的方向及部分文本的方向,有兴趣的朋友可以试下. 首先,从 ...

  2. java16

    1:List的子类(掌握) (1)List的子类特点 ArrayList: 底层数据结构是数组,查询快,增删慢 线程不安全,效率高 Vector: 底层数据结构是数组,查询快,增删慢 线程安全,效率低 ...

  3. video 播放

    视频播放是个坑... HTML5 Video API : https://www.w3.org/2010/05/video/mediaevents.html 虽然界面很丑,但是事件.属性很全. 进行视 ...

  4. MySql学习(四) —— 函数、视图

    注:该MySql系列博客仅为个人学习笔记. 本篇博客主要涉及MySql 函数(数学函数.字符串函数.日期时间函数.流程控制函数等),视图. 一.函数 1. 数学函数 对于数学函数,若发生错误,所有数学 ...

  5. LTE Air interface Channels-----http://www.rfwireless-world.com/Tutorials/LTE-logical-transport-physical-channels.html

    LTE technology works based on three channel types viz. logical channel,transport channel and physica ...

  6. MongoDB中insert方法、update方法、save方法简单对比

    MongoDB中insert方法.update方法.save方法简单对比 1.update方法 该方法用于更新数据,是对文档中的数据进行更新,改变则更新,没改变则不变. 2.insert方法 该方法用 ...

  7. 说说markdown和latex的简单比较

    latex是纯学术风格,写paper写书用 markdown是程序员风格,写笔记贴代码片段用 简单说,latex适合长篇.精致,比如数学公式.图片位置调整.表格样式调整.而markdown就是粗线条, ...

  8. Tomcat配置gzip压缩

    HTTP 压缩能够大大提高浏览站点的速度,它的原理是,在client请求网 页后,从server端将网页文件压缩,再下载到client,由client的浏览器负责解 压缩并浏览.相对于普通的浏览过程H ...

  9. 在eclipse中安装activiti插件

    最近在学习activiti,先学习安装插件吧. 单击help->Install new Software 然后添加资源 name:activiti location:http://activit ...

  10. flex中Event类的使用

    当您创建自己的自定义 Event 类时,必须覆盖继承的 Event.clone() 方法,以复制自定义类的属性.如果您未设置在事件子类中添加的所有属性,则当侦听器处理重新分派的事件时,这些属性将不会有 ...