写点什么

使用 RAML 与 APIkit 以实现 API 需求层次中所定义的目标

  • 2014-12-09
  • 本文字数:3584 字

    阅读完需:约 12 分钟

API 的流行使商业方式出现了快速的改变,各种令人兴奋的创新之举层出不穷,并且围绕着传统的企业级商业模型,涌现出了多种新型的开发者生态系统。API 已经实现了 SOA 愿景中所承诺的景象,即通过简单的接口,在受控的情况下访问数据与业务逻辑。

API 使得底层的应用程序不必受限于预定义的用户界面的功能,这些应用程序的功能可以通过 API 方式为其它应用程序所用,以实现更多更好的服务,而且这种灵活性几乎是没有限制的。

ProgrammableWeb.com 上收集了超过 1 万个公共 API,并且这个数字还在快速增长,看到这一点,我们也应该对 API 在当今世界上的重要性心存敬意。让我们来看看几个 API 应用的例子,以了解各个公司是如何通过 API 来驱动它们的创新的。

Amazon 为用户打造自己的技术平台提供了一个坚实的基础,它不仅为每项功能提供了一个 web 控制台管理器,并且提供了一套完整的 API。这使得 Amazon 的服务能够非常方便地重新包装并整合到客户的解决方案中。与之类似的是,Salesforce 平台上的多数用户操作并非来自 web 用户界面,而是通过使用它们的 API 产生的。Salesforce 允许通过 API 方式方便地访问底层的 CRM 数据,因此该平台的功能能够很容易地整合到客户自己的企业解决方案中。

Amazon 和 Salesforce 的 API 虽然是个有趣的例子,但它的应用只占据了当今所有企业级 API 的冰山一角。当今的企业所采用的 API,大部分是为同一间公司中的一部分内部用户所使用,或者是为某几个固定的合作伙伴所使用。

在公司 API 的设计与构建上,RESTful 方式代表了主流的趋势,在使用度上已经抛离了 SOAP web services 的使用方式,从以下这张由 ProgrammableWeb.com 的 API 目录所创建出的图形就可以得出这一结论。这一趋势也同样延展到了为内部用户及合作伙伴所使用的企业 API。

图 1 – 基于 REST与 SOAP方式构建的 API数量比较(来源: programmableweb.com

虽然这一趋势表现得异常猛烈,但业务目前还没有出现一套完善的解决方案,能够满足 RESTful API 的产品干系人所需的所有需求。实际上,如果有人能够模仿著名的马斯洛需求层次结构理论来规划出一套API 需求层次结构,那他将会得到一个类似于下图的金字塔图形。

换句话说,你必须确保你的API 能够实现这一层次理论的预定目标。如此一来,你就需要以一种高效且可维护的方式实现你的API。当实现完成后,你还需要设法吸引用户的目光,让他们真正开始使用这套API。而在完成了以上工作后,你还需要对这些已经产生价值的API 进行管理与维护。在使用马斯洛需求层次结构的时候,人们会倾向于走捷径的方式,越过底层直奔金字塔顶。这种时候要想想母亲的叮嘱:这不健康!在本文接下来的部分中,我们将采用一种更健康的方式,并且关注于企业级API 设计与实现这两个最基本的需求,同时为你展示如何使用RESTful API 建模语言(RAML)及相关工具,并配合APIkit 的使用,实现这两个基本需求。

使用RAML 进行API 设计

一套RESTful API 的设计总是围绕着这些内容:资源名称、结构、相关的方法、参数、请求与响应的内容体(以实体的方式进行展现),以及响应码。这些设计为开发者创建应用程序定义好了契约。优秀的API 设计应该能够让应用程序的开发者很容易理解这套API 的目的与使用方式,因此很快就能够上手使用。API 的设计也应该为所针对的应用程序类型进行优化,比方说,一个移动应用与一个Web 应用在API 的使用上有不同的限制,移动应用对于API 方法调用的数量和返回的响应数据的大小会更加敏感许多。

为了达到这种良好的API 设计,API 的开发者需要迭代式地以表达式的风格定义API 的结构,并且与预计使用这套API 的应用程序开发者共同进行评审,以此评估这套API 的可用性,以及它是否适合于他们打算创建的应用程序。来看一下RESTful API 建模语言(RAML), RAML.org 对它的描述是:“RAML 是一种能够以简单与简洁的方式描述 RESTful API 的语言。它鼓励重用,允许 API 探索及模式共享。”

RAML 的优势不仅在于它能够允许开发者表达他们的 API 设计,它还有一个重要优势在于:虽然它出现的时间并不长,但已经多个基于它的开源项目存在,这些项目能够促进良好的 API 设计。API Designer 是其中最重要的一个项目,它为使用 RAML 进行 API 结构设计提供了一个编辑器,并且能够在一个互动控制台中实时显示出 API 的更新,以实现用户与 API 之间的交互。

图 2 – API Designer**** 的截图

通过结合使用 RAML 与 API Designer,API 的开发者就可以采取一种 API 优先的设计方式。他们首先会在 API Designer 的编辑器中以 RAML 语言绘制出一套 API 的初步设计,同时将该设计分享给有可能会针对这套 API 进行应用程序开发的开发者们,可以选择只分享 RAML 文档本身,也可以选择将 RAML 自动生成的互动控制台分享给对方。实际上, API Designer 本身就整合了一套用于模拟(mock)的服务,只需提供相应的 RAML 规格说明,该服务就能够自动生成一套关于该 API 的实现。模拟服务能够在互动控制台中进行访问,也可以在类似于 API Notebook 这样的 RAML 工具中访问,甚至可以让在不同设计周期的移动应用进行访问,这也意味着应用的设计可以与 API 的设计同时进行了。它的好处在于能够通过周期性地反馈循环,在开始具体实现之前,就能够为预计的用户提供一套清晰易用于 API。

当 API 的设计结束后,就可以根据 API 开发者的偏好及需求,决定以何种语言及框架具体实现。越来越多的开源项目都提供了根据 RAML 的定义简化 API 具体实现的功能。这些项目包括有:一个为 RAML 生成 JAX-RS 桩(stub)的工具,以及由 MuleSoft 实现的开源项目 APIkit,它能够通过使用 Mule flow 生成一套由 RAML 定义的 API。接下来让我们仔细观察一下 APIkit,看一下它是如何帮助开发者们实现 API 需求结构中的第二个条目——“API 实现”的。

使用 APIkit 实现 API

一套 API 的实现不仅包括了一系列的新业务逻辑,也包括连接与整合的逻辑。很多情况下,连接与整合的逻辑并不简单,需要复杂的自定义代码进行实现。在这种情况下,使用 Mule flows 进行 API 的实现的方式就比使用自定义代码的实现有更大的好处,因为 Mule flows 允许 API 开发者充分利用 MuleSoft Anypoint 平台的能力来交付 API。

这一平台的能力包括有:高级消息处理(比方说将某个消息的片段进行切分,或是整合)、复杂的数据转换,并且能够通过简单而健壮的连接性,连接到多达数百种 SaaS 应用或是本地应用程序的终结点上,这些应用包括 Salesforce、SAP 或是 Microsoft Dynamics,并且支持多种异质的连接协议,例如 FTP/S、MQ(消息队列)、JMS(Java 消息服务)或 AMQP(高级消息队列协议)。

APIkit 是一个开源项目,它极大的简化了在 Mule flows 上开发由 RAML 语言定义的 API 的难度。这个项目中还包括了基于 Maven 和基于 Eclipse 的工具,可直接用于 MuleSoft 的 Anypoint Studio IDE 工具中。对于初学者来说,可以基于一个现有的 RAML API 定义创建一个全新的 Mule 项目,并自动生成一个整合 flow,并将该整合 flow 与由 RAML 规格中定义的每一组资源 / 方法对进行关联。

图 3 – 在 Anypoint Studio**** 中使用 APIkit Project

由 APIkit 生成的 Mule flow 包含了一个默认的实现,它能够返回在 RAML API 中定义的响应的一个示例,这使得该项目能够作为这套 API 的一个模拟实现被使用。这样,开发者就得到了一套完整的 API 实现,它包含了可以运行的模拟版本的逻辑。开发者随后以迭代式的方式,通过使用 Mule 中的各种构件,实现每一组资源 / 方法对的真实的整合逻辑。

开发者还能够完全利用 Anypoint Studio 所包含的各种功能,例如 Visual Flow 调试器,或者在实现高级数据转换时也可以用到 Anypoint DataMapper 。APIkit 还允许将传入的 API 请求路由至现有的 Mule flow 中(而不用完全重新创建新的 flow),它还能够方便地将 Java 及 Mule 中的异常映射至 API 必需返回的 HTTP 响应代码。

最后,APIkit 项目中也包含了一个预定义的交互控制台,这和 API Designer 工具中所包含的(也是动态生成的)控制台是完全相同的。该控制台允许 API 与应用程序的开发者方便地与 API 进行交互,包括浏览它的 RAML 嵌入文档。

当 API 开发者完成了 API 的实现之后,就可以将它部署到 MuleSoft Anypoint 平台上了,可以选择在一个本地的 Mule ESB 实例上托管该平台,也可以选择通过 MuleSoft iPaaS 服务,将 API 托管在 CloudHub 这一云端环境中。

结论

通过这篇文章,我们介绍了 REST API 建模语言(RAML)以及基于它的一些开源项目,包括 API Designer 和 APIkit,并展示了如何使用 RAML 以满足 API 需求结构中的两个最基本的需求,即 API 设计与 API 实现。

关于作者

Reza Shafii MuleSoft 公司的产品管理总监,MuleSoft 是当今世界上使用最广泛的整合平台的供应商。

查看英文原文: Article: Minding the API Hierarchy of Needs with RAML and APIkit

2014-12-09 10:569576
用户头像

发布了 428 篇内容, 共 184.6 次阅读, 收获喜欢 39 次。

关注

评论

发布
暂无评论
发现更多内容

TiDB 慢查询日志分析

PingCAP

数据库 日志分析 TiDB 慢查询

代码手术刀—自定义你的代码重构工具

京东科技开发者

VMware ESXi 8.0U2b macOS Unlocker & OEM BIOS 集成网卡驱动和 NVMe 驱动 (集成驱动版)

sysin

esxi 驱动 网卡 BIOS unlocker

@Transactional事务是真的好用吗

派大星

Spring事务 Java 面试题 互联网大厂面试

基于开源IM即时通讯框架MobileIMSDK:RainbowChat-iOS端v9.0版已发布

JackJiang

网络编程 即时通讯 IM

产品经理职责

执于业务

马斯克开源大模型Grok-1,手把手教你如何使用

京东科技开发者

Sermant热插拔能力在故障注入场景的实践

华为云开发者联盟

开源 华为云 华为云开发者联盟 sermant 企业号2024年4月PK榜

效率提升 80%:go-mongox 让复杂的 BSON 数据编写变得简单

陈明勇

Go 开源 go mongo

kube-apiserver限流机制原理

华为云开发者联盟

Kubernetes 开发 华为云 华为云开发者联盟 企业号2024年4月PK榜

Advanced RAG 02:揭开 PDF 文档解析的神秘面纱

Baihai IDP

AI LLM 白海科技 企业号 4 月 PK 榜 检索增强生成

Sermant热插拔能力在故障注入场景的实践

华为云开源

开源 微服务 服务治理

VMware ESXi 8.0U2b macOS Unlocker & OEM BIOS 标准版和厂商定制版

sysin

esxi 驱动 unlocker dell hpe

Kubernetes大二层网络:挑战与解决方案探索

GousterCloud

cni #k8s

这一次,让我们一起来搞懂MySQL

TimeFriends

AMA live class

Echo!!!

English

【论文速读】| 大语言模型平台安全:将系统评估框架应用于OpenAI的ChatGPT插件

云起无垠

TiDB MVCC 版本堆积相关原理及排查手段

PingCAP

数据库 MVCC TiDB

Vision Pro开发实践(一)

京东科技开发者

MySQL 主从 AUTO_INCREMENT 不一致问题分析

vivo互联网技术

auto_increment MySQL典型案例 replace into

如何打造全国一体化算力体系?

天津汇柏科技有限公司

算力 一体化

我们是如何测试人工智能的(四):模型全生命周期流程与测试图

测试人

人工智能 软件测试

通过Golang获取公网IP地址

GousterCloud

#go 公网ip

探索Kubernetes的大二层网络:原理、优势与挑战🚀

GousterCloud

大二层网络 网络模型 #k8s

一条SQL查询语句是如何执行的

TimeFriends

LangChain初探:为你的AI应用之旅导航

蛋先生DX

#人工智能 LLM #LangChain Prompt 企业号2024年4月PK榜

深度剖析鞋服品牌商品数字化管理的重要性

第七在线

云PBX的内容介绍

cts喜友科技

通信 通讯 云通讯

使用RAML与APIkit以实现API需求层次中所定义的目标_架构_Reza Shafii_InfoQ精选文章