API协议介绍

REST API

REST全称是Representational State Transfer，中文意思是表述（通常译为表征）性状态转移。 它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到：“我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。” 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力， 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深， 但是理论上REST架构风格并不是绑定在HTTP上，只不过目前HTTP是唯一与REST相关的实例。 所以我们这里描述的REST也是通过HTTP实现的REST。

RESTful API

理解RESTful

要理解RESTful架构，需要理解Representational State Transfer这个词组到底是什么意思，它的每一个词都有些什么涵义。

下面我们结合REST原则，围绕资源展开讨论，从资源的定义、获取、表述、关联、状态变迁等角度，列举一些关键概念并加以解释。

• 资源与URI
• 统一资源接口
• 资源的表述
• 资源的链接
• 状态的转移

资源与URI

REST全称是表述性状态转移，那究竟指的是什么的表述? 其实指的就是资源。任何事物，只要有被引用到的必要，它就是一个资源。资源可以是实体(例如手机号码)，也可以只是一个抽象概念(例如价值) 。下面是一些资源的例子：

• 某用户的手机号码
• 某用户的个人信息
• 最多用户订购的GPRS套餐
• 两个产品之间的依赖关系
• 某用户可以办理的优惠套餐
• 某手机号码的潜在价值

要让一个资源可以被识别，需要有个唯一标识，在Web中这个唯一标识就是URI(Uniform Resource Identifier)。

URI既可以看成是资源的地址，也可以看成是资源的名称。如果某些信息没有使用URI来表示，那它就不能算是一个资源， 只能算是资源的一些信息而已。URI的设计应该遵循可寻址性原则，具有自描述性，需要在形式上给人以直觉上的关联。这里以github网站为例，给出一些还算不错的URI：

• Git · GitHub
• GitHub - git/git: Git Source Code Mirror - This is a publish-only repository but pull requests can be turned into patches to the mailing list via GitGitGadget (https://gitgitgadget.github.io/). Please follow Documentation/SubmittingPatches procedure for any of your improvements.
• https://github.com/git/git/blob/master/block-sha1/sha1.h
• Merge branch 'gp/forbid-describe-all-match' into pu · git/git@e3af72c · GitHub
• Pull requests · git/git · GitHub
• Pull requests · git/git · GitHub
• Comparing master...next · git/git · GitHub

统一资源接口

RESTful架构应该遵循统一接口原则，统一接口包含了一组受限的预定义的操作，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。

如果按照HTTP方法的语义来暴露资源，那么接口将会拥有安全性和幂等性的特性，例如GET和HEAD请求都是安全的， 无论请求多少次，都不会改变服务器状态。而GET、HEAD、PUT和DELETE请求都是幂等的，无论对资源操作多少次， 结果总是一样的，后面的请求并不会产生比第一次更多的影响。

资源的表述

资源在外界的具体呈现，可以有多种表述(或成为表现、表示)形式，在客户端和服务端之间传送的也是资源的表述，而不是资源本身。 例如文本资源可以采用html、xml、json等格式，图片可以使用PNG或JPG展现出来。

资源的表述包括数据和描述数据的元数据，例如，HTTP头"Content-Type" 就是这样一个元数据属性。

那么客户端如何知道服务端提供哪种表述形式呢?

答案是可以通过HTTP内容协商，客户端可以通过Accept头请求一种特定格式的表述，服务端则通过Content-Type告诉客户端资源的表述形式。

以github为例，请求某组织资源的json格式的表述形式:

假如github也能够支持xml格式的表述格式，那么结果就是这样的:

应用状态与资源状态

实际上，状态应该区分应用状态和资源状态，客户端负责维护应用状态，而服务端维护资源状态。

客户端与服务端的交互必须是无状态的，并在每一次请求中包含处理该请求所需的一切信息。

服务端不需要在请求间保留应用状态，只有在接受到实际请求的时候，服务端才会关注应用状态。

这种无状态通信原则，使得服务端和中介能够理解独立的请求和响应。

在多次请求中，同一客户端也不再需要依赖于同一服务器，方便实现高可扩展和高可用性的服务端。

但有时候我们会做出违反无状态通信原则的设计，例如利用Cookie跟踪某个服务端会话状态，常见的像J2EE里边的JSESSIONID。

这意味着，浏览器随各次请求发出去的Cookie是被用于构建会话状态的。

当然，如果Cookie保存的是一些服务器不依赖于会话状态即可验证的信息（比如认证令牌），这样的Cookie也是符合REST原则的。

OData

开放数据协议（Open Data Protocol，简称OData）是一种描述如何创建和访问Restful服务的OASIS标准。该标准由微软发起，前三个版本1.0、2.0、3.0都是微软开放标准，遵循微软开放规范承诺书（Microsoft Open Specification Promise）。第四个版本4.0于2014年3月17日在OASIS投票通过成为开放工业标准。

发展简史

协议发起

开放数据协议（Open Data Protocol，简称OData）是由微软于2007年发起的开放协议。当时的开发代号叫“Project Astoria”。于2009年更名为Open Data Protocol。

协议在微软内部的演进

开放数据协议在微软内部演进了三个主要的版本，分别是1.0（2007年），2.0（2009年）和3.0（2009年以后）。

协议成为OASIS标准

2014年3月17日，开放数据协议经由OASIS批准，正式成为开放工业标准。

协议组成

核心协议

核心协议主要定义了开放数据协议的核心语义和行为。它们包括：

• 数据模型
• 服务模型
• 协议和模型的版本管理
• 拓展性
• 数据格式
• HTTP头
• HTTP状态码
• 上下文URL（context URL）
• 数据请求和响应
• 安全性
• 一致性（Conformance）

URL规范

URL规范主要定义了一系列推荐（非强制）采用的构建用于访问OData服务中的数据和模型的URL的规则。它们包括：

• URL的组成部分
• 服务的根URL
• 资源路径
• 查询语句

通用格式定义语言（CSDL）

OData服务的数据模型是通过EDM（实体数据模型）来定义的。通用格式定义语言（Common Schema Definition Language (CSDL)）定义了OData服务的EDM模型的一种XML格式的表现形式。它的内容包括：

• CSDL的命名空间
• 实体模型的封装
• 实体模型的普通特性
• 具体的XML元素和属性介绍

扩展的巴科斯范式（ABNF）

ABNF定义了构建OData请求和响应URL的巴科斯范式。它的包括对以下组成部分的描述：

• 资源路径
• 查询语句
• 上下文URL（context URL）
• 表达式
• OData函数参数的JSON格式
• 命名与标识符（identifiers）
• 数据字面值（literal data values）
• 标头值（header values）
• 标点符号

GraphQL API

GraphQL 是 Facebook 于 2012 年在内部开发的数据查询语言，在 2015 年开源，旨在提供 RESTful 架构体系的替代方案。

GraphQL 既是一种用于 API 的查询语言也是一个满足你数据查询的运行时。 GraphQL 对你的 API 中的数据提供了一套易于理解的完整描述，使得客户端能够准确地获得它需要的数据，而且没有任何冗余，也让 API 更容易地随着时间推移而演进，还能用于构建强大的开发者工具。

示例

一个 GraphQL 服务是通过定义类型和类型上的字段来创建的，然后给每个类型上的每个字段提供解析函数。例如，一个 GraphQL 服务告诉我们当前登录用户是 me，这个用户的名称可能像这样：

type Query {

me: User

}

type User {

id: ID

name: String

}

一并的还有每个类型上字段的解析函数：

function Query_me(request) {

return request.auth.user;

}

function User_name(user) {

return user.getName();

}

一旦一个 GraphQL 服务运行起来（通常在 web 服务的一个 URL 上），它就能接收 GraphQL 查询，并验证和执行。接收到的查询首先会被检查确保它只引用了已定义的类型和字段，然后运行指定的解析函数来生成结果。

例如这个查询：

{

me {

name

}

}

会产生这样的JSON结果：

{

"me": {

"name": "Luke Skywalker"

}

}

查询和变更

• 字段（Fields）
• 参数（Arguments）
• 别名（Aliases）
• 片段（Fragments）
• 操作名称（Operation Name）
• 变量（Variables）
• 指令（Directives）
• 变更（Mutations）
• 内联片段（Inline Fragments）

Schema和类型

• 类型系统（Type System）
• 类型语言（Type Language）
• 对象类型和字段（Object Types and Fields）
• 参数（Arguments）
• 查询和变更类型（The Query and Mutation Types）
• 标量类型（Scalar Types）
• 枚举类型（Enumeration Types）
• 列表和非空（Lists and Non-Null）
• 接口（Interfaces）
• 联合类型（Union Types）
• 输入类型（Input Types）

SOAP API

SOAP (Simple Object Access Protocol) 简单对象访问协议是交换数据的一种协议规范，是一种轻量的、简单的、基于XML（标准通用标记语言下的一个子集）的协议，它被设计成在WEB上交换结构化的和固化的信息。

历史

SOAP是“Simple Object Access Protocol”的缩写。

最新版本SOAP 1.2版在2003年6月24日成为W3C的推荐版本。

SOAP由Dave Winer, Don Box，Bob Atkinson, Mohsen Al-Ghosein于1998年设计，是以 XML-RPC 规范作为创建 SOAP 的依据，该协议在创建初期只作为一种对象访问协议，但由于 SOAP 的发展，其协议已经不单只是用于简单的访问对象，所以这种 SOAP 缩写已经在标准的1.2版后被废止了。SOAP规范由万维网联盟的XML工作组维护。

相关定义

• 基于类对象的传输协议。
• SOAP封装（envelop），它定义了一个框架，描述消息中的内容是什么，是谁发送的，谁应当接受并处理它以及如何处理它们；
• SOAP编码规则（encoding rules），它定义了一种序列化机制，用于表示应用程序需要使用的数据类型的实例；
• SOAP RPC表示（RPC representation），它定了一个协定，用于表示远程过程调用和应答；
• SOAP绑定（binding），它定义了SOAP使用哪种协议交换信息。使用HTTP/TCP/UDP协议都可以。

把SOAP绑定到HTTP提供了同时利用SOAP的样式和分散的灵活性的特点以及HTTP的丰富的特征库的优点。在HTTP上传送SOAP并不是说SOAP会覆盖现有的HTTP语义，而是HTTP上的SOAP语义会自然的映射到HTTP语义。在使用HTTP作为协议绑定的场合中，RPC请求映射到HTTP请求上，而RPC应答映射到HTTP应答。然而，在RPC上使用SOAP并不仅限于HTTP协议绑定。

协议结构

SOAP消息格式：

主要在web服务中运用。

语法规则

构建模块

一条 SOAP 消息就是一个普通的 XML 文档，包含下列元素：

• 必需的 Envelope 元素，可把此 XML 文档标识为一条 SOAP 消息
• 可选的 Header 元素，包含头部信息
• 必需的 Body 元素，包含所有的调用和响应信息
• 可选的 Fault 元素，提供有关在处理此消息所发生错误的信息

语法规则

这里是一些重要的语法规则：

• SOAP 消息必须用 XML 来编码
• SOAP 消息必须使用 SOAP Envelope 命名空间
• SOAP 消息必须使用 SOAP Encoding 命名空间
• SOAP 消息不能包含 DTD 引用
• SOAP 消息不能包含 XML 处理指令

消息基本结构

核心技术

SOAP采用了已经广泛使用的两个协议:HTTP 和XML（标准通用标记语言下的一个子集）。HTTP用于实现 SOAP 的RPC 风格的传输, 而XML 是它的编码模式。采用几行代码和一个XML 解析器, HTTP 服务器( MS 的 IIS 或 Apache) 立刻成为SOAP 的 ORBS。SOAP 通讯协议使用 HTTP 来发送XML 格式的信息。HTTP与RPC 的协议很相似,它简单、 配置广泛,并且对防火墙比其它协议更容易发挥作用。HTTP 请求一般由 Web 服务器软件(如 IIS 和Apache)来处理, 但越来越多的应用服务器产品正在支持HTTP。XML 作为一个更好的网络数据表达方式( NDR)。SOAP 把 XML 的使用代码化为请求和响应参数编码模式, 并用HTTP 作传输。具体地讲, 一个SOAP 方法可以简单地看作遵循SOAP编码规则的HTTP请求和响应, 一个 SOAP终端则可以看作一个基于HTTP 的URL, 它用来识别方法调用的目标。像CORBA/ IIOP一样, SOAP不需要具体的对象绑定到一个给定的终端, 而是由具体实现程序来决定怎样把对象终端标识符映像到服务器端的对象。

XML-RPC

XML-RPC (XML Remote Procedure Call) 是一个远程过程调用（远端程序呼叫）（remote procedure call，RPC)的分布式计算协议，通过XML将调用函数封装，并使用HTTP协议作为传送机制。一个XML-RPC消息就是一个请求体为xml的http-post请求，被调用的方法在服务器端执行并将执行结果以xml格式编码后返回。

XML-RPC 是1998年作为一个 RPC 消息传递协议，将请求和响应封装解析为人类可读的 XML格式。XML 格式基于 HTTP 协议，缓解了传统企业的防火墙需要为 RPC 服务器应用程序打开额外的端口的问题。

XML-RPC 支持的基本数据类型是:int、string、boolean、double 和 dateTime.iso8601。此外,还有 base64 类型用于编码任意二进制数据。array 和 struct 允许定义数组和结构。

XML-RPC 不限制语任何特定的语言，也不是一套完整的软件来处理远程过程，诸如存根生成、对象管理和服务查找都不在协议内。现在有很多库针可以针对不同的语言，比如 Apache XML-RPC 可以用于 Java、Python 和 Perl。

XML-RPC 是一个简单的规范，没有雄心勃勃的目标——它只关注消息，而并不处理诸如垃圾收集、远程对象、远程过程的名称服务和其他方面的问题。然而，即使没有广泛的产业支持，简单的协议却能广泛采用。

示例

Request example

examples.getStateName







41

Response example

SouthDakota

JSON-RPC

JSON-RPC，是一个无状态且轻量级的远程过程调用（RPC）传送协议，其传递内容透过 JSON 为主。相较于一般的 REST 透过网址（如 GET /user）调用远程服务器，JSON-RPC 直接在内容中定义了欲调用的函数名称（如 {“method”: “getUser”}），这也令开发者不会陷于该使用 PUT 或者 PATCH 的问题之中。 本规范主要定义了一些数据结构及其相关的处理规则。它允许运行在基于 Socket、HTTP 等诸多不同消息传输环境的同一进程中。其使用 JSON（RFC 4627）作为数据格式。

约定

由于 JSON-RPC 使用JSON，它具有与其相同的类型系统。JSON可以表示四个基本类型（String、Numbers、Boolean 和 Null）和两个结构化类型（Objects 和 Array）。任何时候文档涉及JSON数据类型，第一个字母都必须大写：Object、Array、String、Number、Boolean、Null。包括 True 和 False 也要大写。

在客户端与任何被匹配到的服务端之间交换的所有成员名字应是区分大小写的。 函数、方法、过程都可以认为是可以互换的。客户端被定义为请求对象的来源及响应对象的处理程序。服务端被定义为响应对象的起源和请求对象的处理程序。

请求对象

发送一个请求对象至服务端代表一个RPC调用，一个请求对象包含下列成员：

• jsonrpc
• method
• params
• id

服务端必须回答相同的值如果包含在响应对象。这个成员用来两个对象之间的关联上下文。在请求对象中不建议使用 NULL 作为 id 值，因为该规范将使用空值认定为未知id的请求。另外，由于JSON-RPC 1.0 的通知使用了空值，这可能引起处理上的混淆。使用小数是不确定性的，因为许多十进制小数不能精准的表达为二进制小数。

响应对象

当发起一个RPC调用时，除通知之外，服务端都必须回复响应。响应表示为一个 JSON 对象，使用以下字段：

• jsonrpc
• result
• error
• id

响应对象必须包含 result 或 error 字段，但两个字段不能同时存在。

错误对象

当一个RPC调用遇到错误时，返回的响应对象必须包含错误成员参数，并且为带有下列成员参数的对象：

• code
• message
• data

示例

用JSON表示中国部分省市数据如下：

var country={name:"中国",provinces:[{name:"黑龙江",citys:{city:["哈尔滨","大庆"]}},{name:"广东",citys:{city:["广州","深圳","珠海"]}},{name:"台湾",citys:{city:["台北","高雄"]}},{name:"新疆",citys:{city:["乌鲁木齐"]}}]}

gRPC-Protobuf

gRPC (gRPC Remote Procedure Calls) 是Google发起的一个开源远程过程调用 (Remote procedure call) 系统。该系统基于 HTTP/2 协议传输，使用Protocol Buffers 作为接口描述语言。

在 gRPC 里客户端应用可以像调用本地对象一样直接调用另一台不同的机器上服务端应用的方法，使得您能够更容易地创建分布式应用和服务。与许多 RPC 系统类似，gRPC 也是基于以下理念：定义一个服务，指定其能够被远程调用的方法（包含参数和返回类型）。在服务端实现这个接口，并运行一个 gRPC 服务器来处理客户端调用。在客户端拥有一个存根能够像服务端一样的方法。

数据编码

JSON一个缺点是非字符串的编码低效，再一个缺点就是信息冗余。JSON 在可读性和编码效率之间选择了可读性，所以效率方面做了一定的牺牲

Protobuf 一方面选用了 VarInts 对数字进行编码，解决了效率问题；另一方面给每个字段指定一个整数编号，传输的时候只传字段编号，解决了冗余问题

在传输的时候只传了字段编号固然可以提高传输效率，但接收方如何知道各个编号对应哪个字段呢？只能事先约定了。就像当年地下工作者一样，一人拿一个密码本。Protobuf 使用 .proto 文件当密码本，记录字段和编号的对应关系

message Demo {

int32 i = 1;

string s = 2;

bool b = 3;

}

Protobuf 提供了一系列工具，为 proto 描述的 message 生成各种语言的代码。传输效率提高，但是工具链也更加复杂

请求映射

因为有 .proto 作为 IDL，Protobuf 可以做很多 JSON 不方便做的事情。其中最重的就是 RPC 描述

package demo.hello;

service Greeter {

rpc SayHello (HelloRequest) returns (HelloReply) {}

}

message HelloRequest {

string name = 1;

}

message HelloReply {

string message = 1;

}

上面的 .proto 文件定义了一个 Greeter 服务，其中有一个 SayHello 的方法，接受 HelloRequest 消息并返回 HelloReply 消息。如何实现这个 Greeter 则是语方无关的，所以叫 IDL。gRPC 就是用了 Protobuf 的 service 来描述 RPC 接口的。

可以简单认为一个 gRPC 请求就是一个 HTTP 请求（不严格）。这个 HTTP 请求用的是 POST 方法，对应的资源路径则是根据 .proto 定义确定的。我们前文提到的 Greeter 服务对应的路径是/demo.hello.Greeter/SayHello 。

一个 gRPC 定义包含三个部分，包名、服务名和接口名，连接规则如下

/${包名}.${服务名}/${接口名}

SayHello的包名是demo.hello，服务名是Greeter，接口名是SayHello，所以对应的路径就是 /demo.hello.Greeter/SayHello

gRPC 协议规定Content-Typeheader 的取值为application/grpc，当然也可以写成application/grpc+proto。如果你想使用 JSON 编码，也可以设成application/grpc+json，只要服务支持都行

• Path : /Service-Name/{method name}
  Service-Name : ?( {proto package name} "." ) {service name}
  Message-Type : {fully qualified proto message name}
  Content-Type : “application/grpc+proto”

示例

请求内容

POST /demo.hello.Greeter/SayHello HTTP/1.1

Host: grpc.demo.com

Content-Type: application/grpc

Content-Length: 1234

响应内容

HTTP/1.1 200 OK

Content-Length: 5678

Content-Type: application/grpc

其他功能

• 认证（ authentication）
• 双向流（bidirectional streaming）
• 流控制（flow control）
• 超时（timeouts）

最常见的应用场景

• 微服务框架下，多种语言服务之间的高效交互
• 将手机服务、浏览器连接至后台