从API源码看API经济 | 从开发角度看应用架构13

前言

本文仅代表作者的个人观点；

本文的内容仅限于技术探讨，不能作为指导生产环境的素材；

本文素材是红帽公司产品技术和手册；

本文分为系列文章，将会有多篇，初步预计将会有26篇。

本篇参考文献：

https://yq.aliyun.com/articles/497806?utm_content=m_42865

一、API的本质

应用程序接口（英语：Application Programming Interface，简称：API），又称为应用编程接口，就是软件系统不同组成部分衔接的约定。由于近年来软件的规模日益庞大，常常需要把复杂的系统划分成小的组成部分，编程接口的设计十分重要。程序设计的实践中，编程接口的设计首先要使软件系统的职责得到合理划分。良好的接口设计可以降低系统各部分的相互依赖，提高组成单元的内聚性，降低组成单元间的耦合程度，从而提高系统的维护性和扩展性。---源自维基百科

上面这段话，有六个字很重要：高内聚、低耦合。

本质上讲，API是对APP的包装，然后对外开放接口，以便被访问。APP和APP间的互相调用，包括读取数据，修改数据等，通过调用API来实现。

二、API的分类

API的分类，大体上分为web类API和非Web类API。我们对这几种进行一下对比：

（本表参考：https://yq.aliyun.com/articles/497806?utm_content=m_42865）

API种类

跨设备

协议

长连接

性质

应用程序API

否

API约定

/

私有

RESTful API

是

HTTP(S)

否

私有

Websocks API

是

Websocket

是

私有

RPC API

是

HTTP(S)

否

私有

微服务API

是

HTTP(S)

否

私有

OpenAPI

是

HTTP(S)

否

公开

非web类API

这里主要指的是非Web应用程序，它为第三方开发者提供了可控访问软件内部功能的接口。例如：Windows AP和Android，他们通过暴露操作系统核心API，使应用程序在获得授权的情况下使用受系统保护的计算机硬件资源（IO设备、GPS等）；浏览器同样为JavaScript准备了API（https://developer.mozilla.org/zh-CN/docs/Web/API），从而使HTML、CSS、JavaScript经过渲染显示出各种程序设定的文字、图像及声音等。

应用程序API通常适用于当前设备内的应用程序交互。

web类API大体又分为以下两类

• JAX-RS RESTful Web Services

• JAX-WS Web Services

JAX-WS

JAX-WS是使用简单对象访问协议（SOAP）的基于XML的Web服务的Java API。 JBossWS是JSR-224 Java API，用于基于XML的Web Services 2.2规范，适用于Red Hat JBoss EAP 7中的JAX-WS。

要为应用程序之间的通信定义标准协议，JAX-WS服务使用使用Web服务描述语言（WSDL）编写的XML定义文件。 WSDL允许IDE（例如JBoss Developer Studio）使用服务定义来创建可以自动与服务交互的客户端，从而简化了Web服务的创建。 但是，此服务定义确实需要为服务的开发人员进行更多维护。与JAX-RS相比，JAX-WS服务还要求客户端和消费者提出更正式的请求，JAX-RS可以仅通过HTTP向各个端点发出请求。

JAX-RS

JAX-RS是用于创建轻量级RESTful Web服务的Java API。在Red Hat JBoss EAP 7中，JAX-RS的实现是RESTEasy，它完全符合JSR-311规范，名为Java API for RESTful Web Services 2.0，并提供了有效开发REST服务的附加功能。

开发人员可以使用注释，将某些类和方法标记为端点来构建RESTEasy Web服务。每个端点表示客户端应用程序可以调用的URL，并根据注释的类型指定HTTP请求的类型。

与其他Web服务方法相比，RESTful Web服务可以使用较小的消息格式（如JSON）。RESTful Web可以对每个端点进行注释，以确定接收数据的格式和返回给客户端的数据格式。此外，RESTful Web服务不需要使用WSDL或类似于使用JAX-WS服务时所需的任何内容。这使得消费RESTful Web服务变得更加简单，因为消费者可以简单地向服务中的各个端点发出请求。

三、如何创建一个Restful API

我们知道，传统意义上的应用架构，通常有http server(Apache HTTP Server )、web container（运行serverlet）、App server（包含EJB container）、数据库。我们一般把http server、web container成为web层、app server称为应用层、数据库成为DB层。

而传统意义上的中间件，如JBoss EAP，它会包含http server、web container、EJB container。

在这里，我们需要强调一下，无论是web server还是EJB container，它们其实只是App server很小的一部分。所以说，即使现在EJB的概念有一些老，app server它还是有很大的价值的。App server（如EAP）有很多功能，它是完全符合Java EE框架和标准的：

• Batch API

• Java API for JSON Processing (JSON-P)

• Concurrency utilities

• WebSocket API

• Java Messaging Service (JMS)

• Java Persistence API (JPA)

• Java Connector Architecture (JCA)

• Java API for RESTful web services (JAX-RS)

• Java API for XML web services (JAX-WS)

• Servlet API

• Java Server Faces (JSF)

• Java Server Pages (JSP)

• Contexts and Dependency Injection (CDI)

• Java Transaction API (JTA)

• Enterprise Java Beans (EJB)

• Bean Validation API 

创建一个Restful API，一般分为三个步骤：

第一步，为web service创建根上下文----第一个源码文件。这个根上下文，是要注册到web container中的。

第二步：在java类中引入http方法----第二个源码文件。这个java类是主任务类，我们可以使用EJB，也可以使用普通的POJO。区别就在于能否被以EJB的方式查询和放到。

第三步:  编译运行应用

Http的方法主要有四类：

HTTP协议定义了协议实现不同操作的几种方法。 除了请求的路径之外，客户还负责指定请求的类型。 以下是方法列表：

• GET：GET方法检索数据。

• POST：POST方法创建一个新实体。

• DELETE：DELETE方法删除实体。

• PUT：PUT方法更新实体

每个HTTP方法都有一个类似命名的注释，用于注释RESTful服务类中的方法。 如果在同一路径上存在两个Java方法，则JAX-RS通过匹配客户端发出的HTTP请求上的HTTP方法和方法上的注释来确定要使用的方法。 以下是RESTful Web服务类的示例：

第一步，为web service创建根上下文。

创建一个新的class：

输入类的名称：

在新类中，添加@ApplicationPath批注，导入库，并将路径指定为/api：

第二步：在java类中引入http方法。

使用@Stateless注释打开并更新com.redhat.training.rest包中的PersonService.java RESTful Web服务，使其成为无状态。

@Stateless

@Stateless表示将java类注册到EJB container中。创建Restful API的时候，可能使用EJB container，也可以不使用EJB container，区别就是是否可以通过EJB的方式访问它

（如果EJB客户端和EJB在同一个JVM进程中本地运行，则客户端可以使用@EJB注释直接向EJB引入注入。如果客户端是远程的，则使用JNDI查找。）。通过普通的POJO也可以创建Restful API。EJB Container摆在那（JBoss EAP中），用不用都可以。

添加@Path注释以在http://localhost:8080/hello-rest/api/persons中提供此Web服务类的端点：

@Path("persons")

效果如下：

为服务定义@Consumes和@Produces媒体类型。

将PersonService.java类中的getPerson（），getAllPersons（），deletePerson（）和savePerson（）方法配置为可用作REST端点。

通过添加@GET注释来公开getPerson（Long id）方法：

更新getPerson（Long id）方法以允许REST服务的使用者通过添加@Path和@PathParam注释来使用REST端点请求具有特定ID的Person：

配置完毕后，达到的效果是：

对http://localhost:8080/hello-rest/api/persons/3的GET请求现在返回ID为3的Person的JSON表示。

将@GET注释添加到getAllPersons（）方法以将该方法公开为REST端点：

配置完毕后，达到的效果是：

对http://localhost:8080/hello-rest/api/persons/now的GET请求返回数据库中所有Person对象的JSON表示。

将@DELETE的注释添加到deletePerson（Long id）方法，以允许HTTP DELETE请求从数据库中删除Person;

与返回单个Person的方法类似，deletePerson方法需要一个ID参数才能从数据库中删除特定的Person。 使用@Path和PathParam批注更新方法，以允许用户在HTTP请求中传递该参数：

最终达到的效果是：

对http：// localhost：8080 / hello-rest / api / persons / 3的DELETE请求现在从数据库中删除ID为3的Person。

将@POST注释添加到savePerson（Person person）方法以创建用于将Person对象保存到数据库的端点：

实现的效果是：对http:// localhost8080 / hello-rest / api / persons /的POST请求现在将该人员保存到数据库中。

第三步：启动EAP server，编译并运行应用

查看EAP日志，war包部署成功：

启动Firefox，然后单击浏览器工具栏中的REST Client插件。

先测试POST：

选择POST作为方法。 在URL表单中，输入http://localhost：8080/hello-rest/api/ persons。

在请求的Body部分中，添加Person实体的以下JSON表示：

查看返回结果：

将body换成davidwei，重新发request.

然后，调整成get，再次发送请求：

返回结果显示我刚刚post的两个任命：

接下来，调用DELETE方法，删除第一个人名：

然后再度发起get，获取信息：

四、AP网关和API管理的区别

API网关的这个概念，其实并不陌生。在Spring Cloud中的zuul，就可以做这个事情。

我们看一下zuul的代码（本图源自Spring Cloud与docker微服务架构实战-周立）。

我们可以看到，应用代码使用zuul，是通用资源注入的方式实现的。

也就是说，我应用想在zuul上注册，代码上实现就可以了。zuul是被动引入的。

如果源码注入了zuul，那么就不会再注册到serverlet中。zuul本身就有http的功能。

所以这实际上有一定的风险，在管理方面，也容易造成困扰。

在某种程度上，API网关zuul 和API管理的功能有重叠。但API管理的功能远远大于zuul。

我们将zuul与API管理进行对比：

其实，API管理无处不在。我举个例子：

首汽约车的app，可以导航对不对？

百度地图的app，可以打车对不对？

首汽约车没有单独为自己的打车软件开发、构建一套导航，也犯不上。它是调用了高德导航的API。

而百度地图则是调用了滴滴打车的API。

所以说，在互联网时代，API经济将会迅速发展。

在这种模式下，单靠写代码，注入zuul的方法，显然是不够的。也很难实现API货币化，更别提API经济了。

接下来，我们看看API经济和API管理。

四、API经济的兴起

API是随着互联网和云计算的兴起而催生的产物。API是三个英文字母Application Program Interface的首字母简写，即应用程序接口。像云供应商亚马逊、互联网巨头Google、社交媒体Twitter，他们的服务都是通过API的方式来提供的。亚马逊的首席执行官Jeff Bezos要求亚马逊的所有开发人员：

• 数据和功能只能通过APIs 来提供给使用者

• APIs 必须设计为便于外部开发人员调用

• 如果你不遵守这个规定，你将被开除

API热在西方出现较早。早在2012年，API就为国际的互联网巨头们带来了非常可观的经济效益：

Salesforce超过一半的收入：Salesforce 23亿美元的年收入中超过的一半的收入是通过API产生的；

• 50亿笔交易：Google 每天通过API处理50亿笔交易

• 130亿笔交易：Twitter每天通过API处理130亿笔交易

• 1万亿笔交易：亚马逊每天通过API处理1万亿笔交易

相对于国外，API经济在国内也已经开始成形，只是还没有引起太大关注。国内像微信、QQ、人人等，都是有开发平台的，开发平台上就有API的管理。API如果被用于商业用途会进行收费，可以根据功能的多少、调用的次数、优先级等分为不同的费用模式。因此，API计费不只是互联网企业的专利，所有的银行、企业甚至政府都可以使用，就像银联在不同银行之间的转账，都属于API抵用。以前企业大多数是在内部的系统之间调用，现在把系统可以提供的服务都用API的形式开放出来，形成API管理门户，分为企业开放者和个人开发者，要经过认证、付费之后就可以使用，付的费用越高，就可以调用更多的服务，比如像百度地图、高德地图和定位GPS。

API的本质是一种服务，无所不在的服务。移动其实是一个载体、一个表现形式；移动在本质上是让服务变得随时随地可以用。手机上的各种APP，其实都是一个服务的入口和访问口，如何来提供这种服务呢？就是后端跟API相关，安全的去使用API。

以航空公司的服务为例，来做一个API平台的使用场景分析：

系统中首先会包含内部的票务系统，剩余票量是多少，乘客信息，座位情况，各方面信息都会显示。

第二，系统会与银行通讯，来验证乘客有没有付款，使用了何种付款方式。

第三，系统还需要和政府打交道来核实乘客身份。比如身份证的信息是否真实，需要和公安部的信息进行比对。公安部也是通过API进行管理，系统一旦被攻破，所有的信息都会有被泄露的危险。其实我们会发现企业和企业之间都是通过API连接的，这就变成了物联网的概念。物联网中的通信不需要人的干预，我们把它叫做机器和机器之间、系统和系统之间的通信。在系统和系统之间的通信也要管理，不管理就会出问题。系统和系统之间就是通过API通信的。

以前大家购买服务都是以一个整包为单位购买，现在拆分得很清楚，因为后端有很多系统，都会分开进行收费，是按照API来计费的。API本质上是很多的函数。一般是很多小函数，就是并列着有很多功能列出来供选择，选择的越多，收的费用越多，这就是跟API收费了。微信也是一样，都是按量去计费的。

API有两种收费标准，第一个是按量计费，第二个是按功能计费。API有提供很多功能，你选择不同功能的套餐，范围越大收费越高。API不再是简简单单的开放一个函数，而是要涉及到开放给谁，怎么计费的问题。这也是API为什么需要门户（Portal）来管理的原因。我不光要告诉你能不能访问，能访问什么，还要告诉你要交多少钱，也就是和费用、经济挂钩了。

以前API一般访问量很小，就是系统和系统之间调用，或者迫不得已调用。当API突然变成服务概念的时候，你会发现API被调用的数量是海量的，这就意味着对API的管理已经势在必行。API的身份要统一管理，API的单点登陆要统一管理，API的能力、API的计费全部要单点管理，这才催生了API经济的概念。

以前API一般访问量很小，就是系统和系统之间调用，或者迫不得已调用。当API突然变成服务概念的时候，你会发现API被调用的数量是海量的，这就意味着对API的管理已经势在必行。API的身份要统一管理，API的单点登陆要统一管理，API的能力、API的计费全部要单点管理，这才催生了API经济的概念。

五、API经济之路

近些年，IT发展的速度呈加速度不断增加的情况。

开发流程：从瀑布、敏捷到devops

应用架构：从单体应用、多层应用到微服务

部署方式：才能高物理机、虚拟机到容器

应用基础架构：从数据中心到云

应用架构的发展道路是：

SOA（面向服务的架构）->  Microservice (Smart endpoint)-> Microservice(simple pipeline) ->API-> Event-based architecture -> Container -> distributed environment-> devops enabled事件驱动

一个完整的API管理方案应该具备上图描述功能。

六、API管理的方案

关于API管理的方案，我们看一下全生命周期API管理魔力象限：

2016年：

2018年：

我们看到红帽的3scale是属于领导者之一。

3scale API管理提供了5个关键功能，它们是：

• 访问控制和安全

• API合同和费率限制

• 分析和报告

• 开发人员门户和交互式API文档

• API帐单和付款

您如何管理API？谁有权接入？您能否为不同类型的用户制定并控制不同的接入权限？您能否控制哪些不同应用可以做到这一点？

接入控制是保证仅有经过成功验证的有效证书的API调用命令能够接入您的API。

3scale为您提供的多种标准的API验证和安全选项，这些选项可以单独或结合使用，用于签发证书并控制接入：

•标准API密钥•应用ID和密钥对•OAuth v1.0和2.0

于安全需求更加复杂的客户，3scale计划提供更多定制选项，例如IP地址和域白名单。

集中仪表板可用于轻松地根据需要签发和撤销证书，并且即时抛弃恶意的API调用，从而使您能够保护后端服务。

3scale的接入控制能力不限于基础的安全和验证。应用和账户计划允许您限制对特定终端、方法和服务的接入，并且轻松地对用户组采用接入策略。分层接入权限使您能够轻松地通过收费计划而从API中获益。

为什么提到合约，IT发展到一定阶段，一方面可以把我们的服务提供给集成商，商业伙伴。

所以，API管理的另外一个很重要的商业价值，那就是收费和限制。

应用计划允许您为API的使用设置速率限制，并控制开发人员组的流量。您可以设置按时间段限制进来的API调用，以保护您的基础架构，并且使流量顺利地流动。对于达到或超过速率限制的应用，自动触发超速提醒，并且为超限应用定义行为。速率限制可应用于收费计划，而且这种计划可以通过配置而对于超过速率限制的调用收取更高的费用。

您可以采用3scale的分析能力监控使用量，触发相关系统中的操作或工作流，并且对于任何计量指标进行追踪。

3scale允许您定义追踪每个终端的指标和方法。根据您的API的用例，您可能希望追踪每个应用或账户的所有以下方面：

••一个或多个服务或终端的整体流量（点击或交易）•CPU时间，例如计算时间或者另一种内部资源的使用量•通过API上传或下载的数据传输量，以MB或GB为单位•每次调用返回的数据对象或记录数量

报告是全方位而且细颗粒度

ActiveDocs

通过基于Swagger框架的3scale ActiveDocs，您的开发人员可以从文档网页实时探索API。只需向您的API添加一个符合Swagger要的规范，将其添加到您的管理门户中，交互式文档就能够供开发人员立即使用。

Swagger是一种开源框架，用于友好且轻松地进行API文档记录和探索。它是API的极为简单但强大的RESTful展示方式。借助Swagger，开发人员可以学习、处理、测试并调试您的API的每个要素。另外，它使得开发人员能够以更简单的方式开发应用。

开发人员门户

3scale提供了内置的最新CMS门户，允许您非常简单地创建带有定制域的自有品牌的中心，用于管理开发人员交互并提高API普及度。

除了文档外，您可以考虑添加用例、代码样本、轻松“开始”信息、文档和定价。

•为应用计划定义并设置定价规则•通过API以自定义的频率生成发票•处理多种类型的信用卡付款

为您的API定义收费计划和支付规则

根据您的API的业务目标以及提供的特性的数据，您可能希望提供免费和收费形式的API接入服务，或者为满足不同的开发人员需求提供多级收费账户接入服务。API的货币化通常依赖定价模式，而大家模式考虑了以下三个因素：

•业务量或使用量

制定计划的最简单方式是基于业务量或使用量。调用量更高的客户一般会通过接入API而获得更多价值。3scale允许您根据全局的API调用次数而采用这种定价模式，或者对于不同的方法进行更加细化的使用。您还可以选择是否希望允许客户在达到计划中规定的调用限制后继续调用，以及是否希望在达到计划限制后对API调用实施超限定价。

•功能

接入某些终端或方法是另一种定义不同计划等级或区分标准和高级计划等级的方式。客户通过支付更多费用而接入更先进的功能或者价值更高的功能，而享受低价或免费的用户仍然能够以高效的方式使用您的API。

•资源使用

定价计划有时考虑客户在每个计划等级内直接或间接产生的基础设施成本。用户数量、带宽消耗以及支持可用性或SLA条款都是将资源使用量用于定价模式的常见方式。

红帽的API管理方案是3scale：

上图中：

API Gateway的作用： 处理API管理策略执行（流量管理）

API Manager的作用：API管理策略配置，分析，计费。

3Scale可以做到：

1.定义API消费者细分，为每个细分配置策略

2. 每个包的指标

API端点访问

费率限制

3.能够通过API创收和创建商业模式

3 Scale中的分析报表功能，可以提供：

（1）API性能和流量模式智能

（2）提供应用程序或开发人员在什么时候访问了那个API endpoint

（3）可以跟踪和监控使用情况，并通过API，应用程序，方法和指标生成报告

（4）可以导出数据并创建自动警报

API的计费和付款：

（1）完全集成的API计费和支付管理

 （2）使客户能够简化API访问的货币化

（3）提供支付解决方案集成：Stripe，Braintree / PayPal，Adyen等

（4）让客户在API消费者和提供者之间实现简单的端到端计费

3 scale有在线体验的服务，地址：https://www.3scale.net

可以自行注册账户：

注册成功以后，登录界面：

查看默认的组织：

查看默认的用户：

查看用户的app：

查看API的调用情况（无调用）

七、集成API管理展示

本实验将展现3scale如何与一个已经存在的API做集成。

本实验使用的api是finto。Finto是芬兰语辞典服务，它可以实现词汇表的出版和浏览。该服务还提供了将叙词表和本体集成到其他应用程序和系统中的接口。

查看finto的API：

接来下，我们在3scale中集成finto API。

登录界面，选择API菜单，选择定义。

增加API定义：

然后保存，选择API集成：

选择集成,API集成菜单中，有三部分内容：API、API网关、client。

在API部分，private base url选择finto api的地址：

在API网关部分，增加mapping rules：

在client配置部分，增加API test get request地址：

然后保存

然后，我们到分析界面，查看API调用，可以看到GET /vocabularies被调用的次数是8：

接下来，通过Postman工具，模拟客户端对api的访问，发一个get请求：

再查查看，GET /vocabularies 被调用次数增加到9：

再次发起3次请求后：

API调用次数增加到：

八、配置Application Plan展示

 3scale API管理平台使用application plan的概念，来定义具有不同API管理策略的API消费者细分。这些策略可以是不同的访问权限集合、onboarding procedures、终端或资源访问权限、货币化模式。

在本实验中，我们将配置一个application plan，然后将一个应用的转到这个plan中。

首先创建一个application plan：

输入名称：

给plan定义limit：

也就是说一个小时最多被访问五次：

然后增加一个feature：

输入名称：

保存后，启用这个feature：API Promotional Campaign

然后，创建一个新的用户：

用户名称：davidwei

用户创建好以后，会自动创建一个默认的app：

我们进入这个app的配置，将这个app指定到刚才创建好的application plan：public api

报错以后，我们看到这个application plan的预设值，已经附加到这个应用上：

九、API分析数据的展现

我们看一下API分析数据的具体内容：

可以下载详细的分析数据表格：

选择以天方式显示：

以小时为单位显示：

从应用视角查看调用：

给用户配置查看报告的权限：

魏新宇

• "大魏分享"运营者、红帽资深解决方案架构师

• 专注开源云计算、容器及自动化运维在金融行业的推广

• 拥有MBA、ITIL V3、Cobit5、C-STAR、TOGAF9.1（鉴定级）等管理认证。

• 拥有红帽RHCE/RHCA、VMware VCP-DCV、VCP-DT、VCP-Network、VCP-Cloud、AIX、HPUX等技术认证。

参考资料：

https://yq.aliyun.com/articles/497806?utm_content=m_42865

3Scale GithubOrganization，https://github.com/3scale

3Scale Blog，https://www.3scale.net/blog/

Red Hat 3Scale FAQ，https://mojo.redhat.com/docs/DOC-1104042

sme-apis mailing list，http://post-office.corp.redhat.com/mailman/listinfo/sme-apis

3Scale One-Stop，https://docs.google.com/document/d/1iYyn666wo1D02Wn0nxCS5NR1_rRmgPvkav-hMWiWyNE/edit#heading=h.1ft5mwfmvjh5