Yun Zhang
Wonderland

Wonderland

Web API 概论 - 引言

Yun Zhang's photo
Yun Zhang
·May 6, 2022·

1 min read

Table of contents

  • Web API 的定义
  • Web API 的非正交分类

Web API 的定义

Web API 的简单定义:一种通过网络,依照预先定义好的规则进行通信的方式。这里网络可以是本地网络,局域网络,或者广域网络。网络的类型会影响API的风格,但是不影响其功能。

在Web API 里,我们还需要定义如下角色:

  • Server:一个程序,这个程序定义了一套API,并且提供了API 的一个实现以及调用机制。
  • Client:一个程序,这个程序使用了Server 定义的API 来服务自己的业务,在某些情况下也可能实现Server 定义的API(Callback)。

这里有两点需要注意,Server 同时负责API 的定义和实现。程序间的依赖关系是Client 单向依赖于Server。

Web API 的非正交分类

考虑如下API 的风格要素,不同要素的组合最终会形成不同的API 类型:

  1. 通讯方式 PULL/PUSH
  2. 通讯信道 ONE-WAY/BI-DIRECTIONAL
  3. 通讯协议 TCP/HTTP
  4. 负载类型 TEXT/BINARY
  5. 生命周期 STATEFUL/STATELESS
  6. 作用范式 COMMAND/DECLARITIVE

通讯方式 PULL/PUSH

PULL - 拉式通信,由Client 向Server 发起通讯并且处理获得结果。PULL 是最常见的API 工作方式,并且通常都会期待一个API 结果,因为Client 对于Server有信息上的请求来满足其自己的业务需要。返回空(EMPTY)也是结果的一种,代表请求已经被知晓。

PUSH - 推式通信,由Server 向Client 发起通讯,对于结果有选择性的处理。因为Client -> Server 的单向依赖关系,Server 并不知晓,也不应知晓Client 的业务,所以这里Server 仅仅处理其通讯部分的结果,甚至在某些情况下连通讯结果都不予理会。

通讯信道 ONE-WAY/BI-DIRECTIONAL

这里的通信信道指的是由谁发起通讯。

ONE-WAY - 仅有一方发起,比如仅支持PULL 或者PUSH。单向通讯通常有着更好的网络拓扑兼容性。

BI-DIRECTIONAL - 双方都可以发起通讯,也就是同时支持PULL 和PUSH。虽然PUSH 通讯可以由Client 发起的长链接来维持,或者借由第三方组件中转来避规对于Client 网络可见性的需求,但是大多数情况下Client 的网络可见性可以极大简化通讯架构。

通讯协议 TCP/HTTP

Web API 都是应用层协议,它可以选择假设在传输层协议(比如TCP)或者应用层协议(比如HTTP)上。

TCP - 选择TCP 一般都是为了传输效率,省掉了额外的应用层开销。

HTTP - 选择HTTP 则是为了方便,HTTP 已经被广泛应用,开发调试生态环境优秀。

负载类型 TEXT/BINARY

负载类型本质上是负载的序列化与反序列化,在选择的时候通常考虑以下因素:表达能力,兼容性,序列化、反序列化效率,最终数据大小,是否开发、Debug友好等。

TEXT - 目前广受欢迎的类型,包含了JSON,XML等一些列格式。TEXT 最大的好处在于表达能力,兼容性,开发、Debug 友好。任何编辑器都可以毫无压力的编辑各种文本类型文件。并且由于网络带宽的提升以及泛压缩能力的应用,其数据大小通常也不再是一个问题。

BINARY - 一些远古RPC 协议或者极端注重效率的协议比较青睐的负载类型。

生命周期 STATEFUL/STATELESS

STATEFUL - Server 具有自己的状态(例如包含一个或者多个FSM)并且通过API 暴露,对API 调用会改变Server 的状态。这对Client 在流程控制和错误处理上提出了更高的要求,因为Client 需理解Server 的状态流转流程并且确保某些状态流转的发生(比如某个FSM 的终态)。

STATELESS - 目前比较流行的API 设计理念。Server 不再对外暴露其状态流转,其内部可以更好地封装流程处理,并且提供更加易用的API。这种设计也可以更好的支持Server 的横向扩展(Scale Out)和负载均衡(Load Balance)。

作用范式 COMMAND/DECLARITIVE

和生命周期紧密相关,STATEFUL 的设计通常对应命令式的API,而STATELESS 的设计则对应声明式API。

COMMAND - 命令式API 自古以来就非常契合程序思维,给计算机一条指令,计算机执行并返回结果。RPC 也是命令式API 的一个典型表现。

DECLARITIVE - 声明式API 现在越来越流行,因为它提供了更好的封装,Client 可以实现的更简单,并因此简化程序间的集成。声明式API 仅声明目标或者目标状态,如何达成目标由Server 自己决定。

 
Share this