金融服务中基于Web服务的应用程序编程接口技术规范

ICS03.060

A11

中华人民共和国国家标准

GB/TXXXXX—XXXX

金融服务中基于Web服务的应用程序接口

Web-service-basedApplicationProgrammingInterfaceinFinancialServices

（ISO/TS23029:2020）

征求意见稿

XXXX-XX-XX发布XXXX-XX-XX实施

GB/TXXXXX—XXXX

前言

本文件按照GB/T1.1-2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规则起

草。

本文件使用重新起草法修改采用ISO/TS23029:2020《金融服务中基于Web服务的应用程序接口》。

本文件由中国外汇交易中心暨银行间同业拆借中心提出。

本文件由全国金融标准化技术委员会（SAC/TC180）归口。

本文件负责起草单位：中国外汇交易中心暨全国银行间同业拆借中心。

本文件主要起草人：。

本文件为首次制定。

II

GB/TXXXXX—XXXX

金融服务中基于Web服务的应用程序接口

1范围

本文件定义了API生态系统的框架、功能和协议，以实现在线同步交互。具体内容包括：

——定义了用于开发API的逻辑和技术分层方法，包括转换规则，不包括特定的逻辑模型（例如

ISO20022模型），但作为指导，它们将在特定情景下被引用；

——主要是从RESTful设计的角度考虑，但也会考虑其他场景提供的架构样式（如WebSocket和

Webhook）；

——定义了API的设计原则、基于Web服务的API规则、数据有效负载和版本控制；

——列出了与API设计的安全性、身份和注册相关的注意事项。

本文件不适用于以下内容：

——金融服务中API实施的特定技术规范；

——基于ISO20022特定报文格式开发的JSONAPI，例如PAIN、CAMT、PACS；

——由特定法律框架定义或确定的技术规范。

2规范性引用文件

下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，

仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本

文件。

ISO20022-1金融服务—金融业通用报文方案—第1部分：元模型（Financialservices—

Universalfinancialindustrymessagescheme—Part1:Metamodel）

ISO20022-3金融服务—金融业通用报文方案—第3部分：建模导则（Financialservices—

Universalfinancialindustrymessagescheme—Part3:Modelling）

ISO20022-4金融服务—金融业通用报文方案—第4部分：XMLSchema生成（Financialservices

—Universalfinancialindustrymessagescheme—Part4:XMLSchemageneration）

JSONSchemadraft4specification[J/OL].Cloudflare,A.Wright,H.Andrews.

/html/draft-handrews-json-schema-01

JSONAPIV1.0[EB/OL]./about/

ExtensibleMarkupLanguage(XML)1.1(SecondEdition)[J/OL]/TimBray,JeanPaoli,C.M.

Sperberg-McQueen,etal./TR/2008/REC-xml-20081126/

OpenAPISpecificationV3.0.2[EB/OL].https://swagger.io/specification/

3术语和定义

以下术语和定义适用于本文件。

3.1

应用程序接口applicationprogramminginterface（API）

指一组明确定义的方法、函数、协议、事务或命令，应用程序软件通过使用它和编程语言开发工具

来调用服务。API适用于不同类型的软件，包括基于Web的系统。

3.2

超文本传输协议hypertexttransferprotocol（HTTP）

3

GB/TXXXXX—XXXX

指一种用于分布式、协作式和超媒体信息系统的应用层协议。超文本是一种结构化的文本,在包含

文本的节点之间使用逻辑链接(也叫超链接)。

3.3

幂等性idempotency

在计算机技术中，幂等性，也称为幂等，是一个操作特征，这意味着如果多次调用该操作，不会产

生额外的影响。因为很难限制冗余访问，所以幂等操作通常用于设计基于Web的系统。

3.4

JS对象简谱javascriptobjectnotation（JSON）

指轻量级的、基于文本的数据格式。

3.5

表现层状态转换representationalstatetransfer（REST）

表现层状态转换，也称为RESTful，是一个分布式超媒体系统的架构样式，由RoyFielding在其2000

年所著的论文中提出。

3.6

资源路径resourcepath

旨在指定与给定API请求相关的资源所在地址。

3.7

资源跃点resourcehop

指一个基于资源类型和标识符的资源定位器，资源路径是一个或多个资源跃点的链。

3.8

结构化描述语言RESTfulAPIdescriptionlanguage

指用于提供RESTfulWebAPI的结构化描述的语言，该API对人工和自动化的机器处理都很有用。

3.9

简单对象访问协议simpleobjectaccessprotocol（SOAP）

指用于在计算机网络中实现Web服务时交换结构化信息的一种协议规范。

3.10

网络套接字websocket

指一个允许在受控环境中运行不受信任代码的客户端与已选择通过该代码进行通信的远程主机之

间的双向通信的协议。

3.11

网络钩子webhook

指由某些事件触发的用户定义的HTTP回调，例如将代码推送到存储库或将评论发布到博客。

3.12

可扩展标记语言extensiblemarkuplanguage（XML）

可扩展标记语言，由W3C创建的数据格式标准。

4缩略语

以下缩略语适用于本文件。

URIUniformResourceIdentifier统一资源标识符

4

GB/TXXXXX—XXXX

HATEOASHypermediaastheengineofapplication超媒体即应用状态引擎

state

SMTPSimpleMailTransferProtocol简单邮件传输协议

JWTJsonwebtokenJsonweb令牌

5设计原则

本节介绍了开发WebAPI的原则。它涵盖了在金融服务中开发API时应首先考虑的独立设计和适用于

特定类型API的原则，并在WAPI样式下进行了更详细的讨论。

5.1标准兼容性

WAPI主张尽可能使用ISO数据标准，并将其作为最佳选择，以促进互操作性。

5.2可扩展性

API的设计应尽可能具有可扩展性，数据标准可能会更改，但API不会。这是为了确保它们的使用能

够适应未来的用例或场景。

5.3不可否认性

不可否认性对WebAPI中的数据交换的有效性来说非常重要，它可提高待交换的数据的准确性。数

字签名可以在API中使用。

5.4Web资源唯一标识符（ID字段）

Web资源应具有可用于标识资源的唯一标识符（例如：主键），这些唯一标识符用于构造URL/URI

以标识和寻址特定资源。

5.5幂等性

对于WebAPI，应预先考虑幂等性，这在WAPI样式中有介绍。

5.6状态

预先考虑需要哪个状态。

6相关技术

本节对相关技术进行阐述，并提供其在金融服务中使用API的一些背景信息。它不包括上面所述的

术语和定义，也不包括如何处理该技术的具体指导，如下所述（WAPI样式）。

6.1表现层状态转换（REST）和简单对象访问协议（SOAP）

REST和SOAP提供了访问Web服务的方法，并且需要考虑同时使用。

6.1.1表现层状态转换（REST）

REST或RESTfulWeb服务提供了传输资源的表示状态，并指定要在此资源上处理的操作方法（请参

阅术语和定义）。REST是最受欢迎的构建Web服务或定义WebAPI的方法，因为它简单，并且与HTTP等现

有Internet标准兼容。

API通常使用REST，因为它更有效并且需要更少的处理。在大多数使用RESTfulAPI的金融场景中，

终端用户向服务器发送消息，然后服务器快速响应。例如，在交易系统中下订单或在账户上请求余额。

REST结构可用于实现这些通信请求或响应。具体可由以下六点来描述REST的结构特性:

——统一接口:统一接口约束定义了客户端和服务器之间的接口。它简化和解耦了REST结构，使每

个部分都能够独立扩展。

——无状态:一个客户端可以向服务器发送多个请求;但是，每个请求都必须是独立的，也就是说，

每个请求都必须包含所有必要的信息，以便服务器能够理解它并相应地处理它。在这种情况下，

服务器不能保留关于客户端状态的任何信息。任何信息状态都必须保留在客户端上——比如会

5

GB/TXXXXX—XXXX

话。

——可缓存的:由于许多客户端访问相同的服务器，并且经常请求相同的资源，因此有必要缓存这

些响应，以避免不必要的处理并显著提高性能。

——客户端-服务器。统一的接口将客户机与服务器分开。这种分离的关注点意味着，例如，客户

端不关注数据存储，数据存储仍然是每个服务器内部的，这样客户端代码的可移植性就会提高。

服务器不关心用户界面或用户状态，这样服务器可以更简单，可扩展性更强。只要不改变界面，

服务器和客户端也可以独立更换和开发。

——分层系统:客户端通常无法分辨它是直接连接到终端服务器，还是中间连接。通过启用负载平

衡和提供共享缓存，中间服务器可以提高系统的可伸缩性。层还可以强制执行安全策略

——代码按需(可选):这个条件允许客户按需运行一些代码，也就是说，通过小程序或脚本将部分

服务器逻辑扩展到客户端。因此，即使使用服务器提供完全相同的服务，不同的客户也可能以

特定的方式行事。由于该项不是体系结构本身的一部分，因此被认为是可选的。它可以用于执

行一些更有效或更快的客户端服务。

6.1.2简单对象访问协议（SOAP）

SOAP是一种消息传递的协议规范，用于在计算机网络的Web服务中交换结构化信息。它使用XML消息

格式，并通常使用HTTP或SMTP用于协商和传输消息。

SOAP允许在不同操作系统（例如Windows和Linux）上运行的进程使用XML进行通信。由于HTTP等Web

协议已在操作系统上安装并运行，因此SOAP允许客户端调用Web服务接收独立于语言和平台的响应。

6.2网络套接字（WebSocket）和网络钩子（Webhook）

WebSocket和Webhook协议存在于REST无法满足的场景中，例如支持未经请求的响应。特别是：

——对于客户端到客户端的体系结构，可以使用Webhook；

——对于客户端到服务器体系结构，可以使用WebSocket；

——用于任何类型的发布/订阅实现。

6.2.1网络套接字（WebSocket）

如RFC64551)中所述，WebSocket协议支持客户端与远程主机之间进行全双工通信。此处所用的安全

模型是Web浏览器常用的基于原始的安全模式。

该技术的目标是为基于浏览器的应用程序提供一种机制，该机制需要与不依赖于打开多个HTTP连接

的服务器进行双向通信。在大规模数据传输或由服务器驱动的事件的情况下，WebSocket比HTTP表现更

好，例如市场数据分发和市场公告发布。其特征如下：

——大多数浏览器都支持WebSocket协议（IETFRFC6455），但客户端可能是任意软件代理。

——会话由协议升级的HTTP请求启动。TLS握手用于校验和验证，并且密码套件被启用以确保隐

私和不可否认性。

——初始握手后，会话成为双向异步消息传递协议。因为任何一方都可能推送未经请求的消息，所

以不需要轮询机制。

——定义了两个子协议：文本消息（例如JSON或XML），以及二进制消息（例如，简单的二进制

编码）。如果需要，对等体可以支持多个子协议。其他子协议可以在IANA注册，例如ISO20022

消息。

——WebSocket通过TCP分层。它继承了其可靠性和流量控制功能。但是，WebSocket通过TCP流

构建消息。因此，应用程序无需关注框架。

——没有会话协议标头强加于应用程序消息。消息是自包含的，因此可以作为一个单元进行序列

化或转发（与HTTP相反，其中语义信息分散在有效负载、URI和头部上）。

——会话协议没有提供将请求与响应相关联的机制，因为它是事件驱动的协议而不是请求/响应。

事件的相关性将在具有事务ID等的应用层处执行。

6.2.2网络钩子（Webhook）

1)/html/rfc6455

6

GB/TXXXXX—XXXX

Webhook有时被称为“反向API”。Webhook是“用户定义的HTTP回调”。它通常基于事件触发，例

如将代码推送到存储库或将评论发布到博客。事件触发时，源站点会对为webhook配置的URL发出HTTP

请求。用户可以将它配置为使一个站点上的事件调用另一个站点上的行为。Webhook用途很多，常见用

途是使用持续集成系统触发构建或通知错误跟踪系统。由于它使用HTTP，因此无需添加新的基础架构即

可将它集成到Web服务中。

6.3超文本传输协议（HTTP）

超文本传输协议（HTTP）是一种用于分布式、协作式和超媒体信息系统的应用层协议。超文本是结

构化文本，它使用包含文本的节点之间的逻辑链接（超链接）。HTTP是交换或传输超文本最常用的协议。

6.4JS对象简谱（JSON）和可扩展标记语言（XML）

在Web通信场景中，最常用的两种用于数据交换的结构化数据格式是XML和JSON[RFC82592)]。

6.4.1JS对象简谱（JSON）

JSON是一种基于文本的轻量级数据格式，广泛用于基于Web的通信，包括作为XML的替代品。

6.4.2可扩展标记语言（XML）

XML是由W3C3)创建的数据格式标准。

6.5内容协商

内容协商是指客户端和服务器协商从服务器返回的内容样式的机制。客户端可以使用以下HTTP标头

请求特定样式的文档：Accept、Accept-Language、Accept-Charset。它们分别指文档的格式、文档的

语言和文档的字符集。

收到HTTP请求后，服务器必须查看Accept标头以确定它是否可接受。如果不可接受，则服务器必须

返回HTTP406NotAcceptable状态代码。如果请求是可接受的，则服务器必须在Content-Type响应头

中为请求附加正确的MIME类型。服务器可以选择遵循浏览器的语言和字符集首选项以格式化响应。如果

服务器选择遵循Accept-Language和Accept-Charset标头，则使用的响应标头应为Accept-Language标头

的Content-Language，Content-Type应附加字符集信息。

6.6RESTfulAPI描述语言

RESTfulAPI描述语言是一种形式语言，旨在提供RESTfulWebAPI的结构化描述，该API对人工和

自动化机器处理都很有用。

RESTfulAPI的描述语言通常是中性的，与语言无关，与行业无关。它并没有定义API本身，但对于

API生态系统的设计者、程序员和用户非常有用，特别是在构建大规模的API时。本质上，RESTfulAPI

描述语言是一种软件工程方法学，而不是一种计算机架构或通信技术。围绕RESTfulAPI描述语言的社

区很活跃，而且情况仍在变化。到目前为止，这方面最活跃的项目是OpenAPI、RAML和APIBlueprint。

——OpenAPI规范

最初称为Swagger规范，是一个用于描述、生产、消费和可视化RESTfulweb服务的机器可读接口文

件的规范。自2016年起，它成为Linux基金会的开源协作项目，最新版本是3.0。

URL:https://swagger.io/specification/

——RAML

RAML是一种基于yaml的语言，用于描述RESTfulapi。它提供了描述RESTfulapi或实际上是RESTful

api所需的所有信息。尽管RAML是基于RESTfulapi设计的，但它能够描述那些不遵守REST的所有约束的

api(因此描述为“实际上是RESTful的”)。它鼓励重用，支持发现和模式共享，并旨在基于优点的最佳

实践的出现。

URL:/

——API蓝图

2)/html/rfc8259

3)/html/rfc6455

7

GB/TXXXXX—XXXX

API蓝图是一种面向文档的webAPI描述语言。API蓝图本质上是一组建立在用于描述webAPI的

Markdown语法之上的语义假设。

7命名规范

下表列出了WAPI应遵循的适用字符大小写的约定。

表1API元素命名规范

API元素规则示例

尽管RFC2616指定HTTP标头不区分大Accept-Charset

小写，但在API规范中，最佳做法应该Train-Case是使用最广泛的形式。

是对于所有标头定义采用相同的字符单词大写并用连字符分隔(-)

HTTP标头大小写。

WWW-Authenticat

[RFC6648]应避免使用自定义专有的首字母缩略词应大写

“X-”类型的标头e

最常用的形式是snake_case:单词为小写，用下划

currency_code

线分隔(_)

查询

lowerCamelCase:删除空格和

参数

标点符号，除第一个单词外，currencyCode

每个单词的首字母大写

资源路径参见以下

最常用的形式是snake_case:单词为小写，用下划

线分隔(_)currency_code

请求正文lowerCamelCase:删除空格和

标点符号，除第一个单词外，currencyCode

每个单词的首字母大写

以上是变量，用于数据类型UpperCammelCase的定义。

示例：

"country":{

数据类型CountryCode

"title":"Ctry,Country",

"description":"Countryoftheaddress.",

"$ref":"#/definitions/CountryCode"

}

8资源路径

资源路径旨在指定与给定API请求相关的资源所在地址。

8.1资源跃点

此资源路径是一个或多个资源跃点的链。每个资源跃点都基于以下组件构建：

——所有资源跃点都必须使用资源类型；

——除最后一个资源跃点外，资源标识符是必需的（见下文）

当在资源路径中指定多个资源跃点时，假设除了第一个资源之外的每个资源在语义上链接到路径中

的前一个资源。

跃点元素规则示例

8

GB/TXXXXX—XXXX

资源类型标准模式是使用复数形式的资源名称来指定相同类型的资源集合(例orders

如：“orders”,而不是“order”。

)payment-requests

资源类型最广泛使用的字符大小写惯例是“脊椎案例”。单词为小

写，用连字符分隔。

资源ID可以放在HTTPURI中的字符串，用于标识API服务器端的单个资源。000235698741

pmtrqst1652

此ID最可能由API服务器提供。

必须标识资源路径上的任何资源跃点（最后一个除外）。

注：资源类型和ID是请求URI的不同元素，以斜杠分隔(/)。

示例：

资源跃点

/orders/000235698741

/payment-requests/pmtrqst1652

8.1.1单一资源和资源合集

资源路径中的最后一个资源跃点是API请求的有效目标。如果该跃点有，则表示目标实际上是与ID

匹配的单个资源。如果该跃点没有，则目标是所有可访问资源的集合ID。

示例：

资源目标

/orders所有订单的集合

/orders/000235698741订单集合中的特定订单

/payment-requests/收集所有付款请求

/payment-requests/pmtrqst1652付款请求集合中的特定项目

/payment-requests/pmtrqst1652/instructions收集给定付款请求中的所有指令

/payment-requests/

收集给定付款请求中的所有指令

pmtrqst1652/instructions/1526

9WAPI样式

本节介绍如何设计和实现API的各个部分。尽可能为金融服务中的WebAPI提供决策依据。

本文档涵盖了三种WAPI样式：REST、异步消息和服务推送。众所周知，在金融服务中还有其他方法，

但这些被认为是覆盖用例的主要例子。

9.1表现层状态转换（REST）

——对于需要在短时间内发送带有回复的消息的金融场景，建议基于RESTfulapi构建，例如，在

交易系统中下订单。

——REST是一种用于开发Web服务的架构样式，它定义了一组约束，包括客户端-服务器体系结构、

统一接口、无状态等。

——与WAPI最相关的约束是统一接口和无状态会话：

统一接口：统一接口约束定义了客户端和服务器之间的接口。它简化并解耦了REST架构，

使每个部分都能独立扩展。RESTfulAPI通常使用HTTP方法GET，POST，PUT和DELETE

来构建统一的接口来操作资源。

9

GB/TXXXXX—XXXX

无状态：一个客户端可以向服务器发送多个请求;但是，每个请求都必须是独立的，也就

是说，每个请求都必须包含所有必要的信息，以便服务器能够理解它并相应地处理它。在

这种情况下，服务器不能保留关于客户端状态的任何信息。任何信息状态都必须保留在客

户端上——比如会话。

——REST样式是分布式超媒体系统中架构元素的抽象，架构数据元素的本质和状态是REST的一个

关键方面。与WAPI最相关的数据元素是资源和资源标识符（例如URI），表示和表示元数据

（例如，HTML，JSON，XML）。

——从客户端和服务器的角度来看，使用REST的一个主要好处是，基于REST的交互，其使用的结

构是惯于使用互联网超文本传输协议（HTTP）的任何人都熟悉的。换句话说，建议使用HTTP

来实现RESTfulWAPI。

——总之，设计和实现RESTfulWAPI的关键因素包括：统一接口，HTTP方法使用，无状态，幂等

性，资源和资源标识符用法。

使用示例：访问账户

图1访问账户的REST应用

9.1.1统一接口

资源标识符

请求中应使用URI作为资源标识符。交换的信息应该是资源的表示，使用特定语法表示（建议使用

XML或JSON），具体取决于请求和服务器的实现细节。

可操作资源

客户端持有的资源表示法应该具有足够的信息来修改或删除服务器上的资源（如果允许）。客户端

持有的资源表示形式应该具有足够的信息，如果允许的话可以用来修改或删除服务器上的资源。

10

GB/TXXXXX—XXXX

注释

每条消息都应包含足够的信息来描述如何处理它。例如，应使用网络媒体类型来指定要调用的解析

器。响应还应明确指出其缓存能力。

超媒体即应用状态引擎

客户端应通过正文内容、查询字符串参数、请求标头和请求的URI（资源名称）来提供状态。服务

应通过正文内容、响应代码和响应标头向客户提供状态。

除了上面的描述之外，在必要时，HATEOAS还意味着链接包含在返回的正文（或标题）中，以提供

用于检索对象本身的URI。

在这样的体系结构中，每个响应将包含资源的后续表示形式。因此，进入“授权”状态的响应还将

包含三个新的URI，指向三个状态（授权，拒绝和接受）。

超媒体也可用于提供有关客户端下一步能够执行的操作的信息：

——分页功能；

——进一步操纵资源或子资源或链接资源。

当使用HATEOAS时，为了确保响应中不同部分的命名是一致的，它应该遵循v1.0的原

则：/about/。

9.1.2应用标准HTTP方法

使用指南

——使用标准的HTTP方法POST，GET，PUT和DELETE来操作资源，具有以下含义：POST=新建，

GET=读取，DELETE=删除，PUT（或PATCH）=更新。

——使用POST创建没有任何指定资源标识符的资源。使用POST成功创建资源后，服务器的最佳实

践是：

为新创建的资源分配标识符；

使用“201Created”和HTTP状态以及新创建的资源的位置来回答客户端。

——使用GET检索使用其标识符指定的给定资源，或者可能通过某些搜索条件指定的一组资源。关

于GET请求的一些其他说明：

可以缓存GET请求；

GET请求保留在浏览器历史记录中；

GET请求可以加入书签；

处理敏感数据时不要使用GET请求；

GET请求有长度限制。

——由于对GET的限制，在处理敏感数据或参数太多时允许使用POST进行读取。

——使用DELETE删除使用其标识符指定的给定资源，或者删除可能通过某些搜索条件指定的一组

资源。

——使用PUT进行“完整”更新，即当整个资源位于PUT请求体时，将完全替换先前的资源。换句

话说，PUT必须是完整的资源更新，在PUT请求中应该发送所有属性值以保证幂等性。

——当更新请求中仅存在资源的一个或几个属性时，使用PATCH进行部分更新，但不替换资源本身。

使用RFC7396作为PATCH的主体。这是最简单，最直观的方式，也是首选方式。尽管RFC7396

依赖于使用JSON作为语法，但其中指定的规则也可以在使用XML时应用。

示例：

表2应用标准HTTP方法示例

URLPOSTGETPUTPATCHDELETE

11

GB/TXXXXX—XXXX

/orders创建一个订单列出订单批量更换或创批量更新订删除所

(为创建订单返建订单4)单5)有订单

回一个id)

/orders/00023569874错误6)获取该订如果存在，则替换如果存在，更新删除该

1单细节订单，否则创建订订单，或更新失订单

单7)败

9.1.3无状态会话

无状态会话表明，处理请求的必要状态应由客户端定义并包含在请求本身中，要么作为URI的一部

分，要么作为查询字符串参数的一部分，要么作为正文或标题的一部分。在服务器进行处理之后，应将

适当的状态传送回客户端。

这与“会话”相反，后者在多个HTTP请求中维护状态。在REST中，客户端必须包含服务器的所有信

息以完成请求，如果该状态必须跨越多个请求，则根据需要重新发送状态。

状态和资源都需要：

——状态，或应用程序状态，是服务器为完成当前会话或请求所需的数据请求而关心的状态；

——资源或资源状态是定义资源表示的数据——例如，存储在数据库中的数据。将应用程序状态视

为因客户端和每个请求而异的数据。另一方面，资源状态在请求它的每个客户端都是不变的。

9.1.4幂等性

通常，如果没有额外的设计，WebAPI不应该是“读取”应用程序的幂等。基于以下原则，建议Web

API“写入”应用程序是幂等的：

——建议用于创建，更新或删除资源的API是幂等的。此功能的目的是允许API用户重试因超时或

意外错误而失败的API请求；

——对于可能具有破坏性的操作，建议在API请求中实现幂等性主键；

——建议API的用户在使用相同的幂等主键时不应该更改请求体，如果API用户更改了请求正文，

则API提供程序不会修改结束资源；

——如果API请求者已收到具有相同主键的第一个请求，则应该将请求视为幂等的；

——如果请求成功，API提供商应该以资源的当前状态响应请求，API提供程序可以使用消息签名

（如果已实现）以及幂等主键来确保请求正文未更改。

9.1.5统一资源标识符的组成

4)在替换的情况下，有效资源的ID不能在有效载荷中提及（由应该替换或放在正文中）。

5)批量修补程序是批量更新资源的危险且不推荐的方法。

6)'POST'是用于创建尚不存在的资源。因此，对现有资源执行POST会被视为错误。除非POST被PUT或PATCH覆

盖。

7)让客户端创建资源ID是不好的做法。始终应该是由服务器来创建。

12

GB/TXXXXX—XXXX

图2URI的组成

resource_path可以包括多个适用的资源，并伴有资源ID。通常URL不包含动词，因为它们是基于资

源路径的。

在Type，Issuer，Version概念中，URI可以通过定义{service}的方式来反映这一点，即反映Type

（whatIcall）和Issuer（whoprovidedthecall）。

示例：/refdata/v1/bics

9.1.6处理资源之间的关联

公开URI路径中的资源之间的关联关系。但保持URI中的关系最小化，通常保持主键和所受影响的资

源的关联就足够了。

示例：GET/refdata/v1/bics/PVRBRU4VXXX/ssis

含义：“获取BICPVRBRU4VXXX的所有SSI”，其中BICPVRBRU4VXXX被当做主键。

9.1.7请求参数用法

总则

请求中可能有各种类型的“参数”：

——定位器（资源标识符或特定操作）；

——过滤器（提供搜索，排序或限制结果的参数）；

——内容（要存储的数据）。

由不同的占位符放置这些参数：

——URI查询参数（URI后面的“?”问号部分）；

——URI路径（URI后面的主机名或“完全限定域名”部分，以及“？”问号前面的部分）；

——HTTP请求正文；

——HTTP请求头。

表3请求参数用法示例

URI请求URI路径请求体请求头

定位器X

过滤器X

状态X

内容X

状态

状态在标题中设置，具体取决于状态信息的类型。

13

GB/TXXXXX—XXXX

内容

内容只有一个所处位置，即请求体，它可以是有效负载/正文内容（XML或JSON），也可以是多部分

/表单数据请求。资源的内容应仅在正文中，而不是其他位置，例如标题。

资源过滤器

定位器属于URL路径。

示例：/bics/CITIUS33

注：其中CITIUS33是“bic”类型的特定资源的id。

过滤器放在查询字符串中，因为虽然它们是获取正确数据的一部分，但它们只是返回定位器返回内

容的子集。

有两个例外，即定位器和过滤器可以进入HTTP请求体而不是URI：

——当URL的长度超过需要处理这些URL的最大长度（2K）时；

——当定位器或过滤器中的信息需要加密时，这些通常会放在URL中，但URL往往以未加密的形式

存在于日志文件或跟踪工具中，因此URL不适合保密信息。

对于如果API需要支持这两种特殊情况，则允许使用POST而不是GET，在POST的URI查询部分使用

method=GET，并且使用包含URI查询部分的POST主体会出现在正常的GET中。

属性与搜索标准

将资源属性和搜索条件放在“？”后面。

区分资源与其属性之间的关系。通常两个资源之间的关系通过URL中的路径表示，而资源的属性放

在“？”后面。

示例：/bics/PVRBRU4VXX/ssis?currency_code=USD&ssi_category=COPA

含义：

注1：“BICPVRBRU4VXX的所有SSI”，货币代码“USD”和SSI类别“COPA”。

注2：URI查询中的属性应该是资源的子元素。

注3：URI查询中的属性顺序没有意义。

为属性指定多个允许值

在属性名称和“=”符号后面使用逗号分隔的值列表进行指定。

示例：GET/bics?address.country=Belgium,Germany

注1：当其地址所在国家/地区为比利时或德国时，返回bics。

过滤器

减少每个资源返回的属性列表（过滤）。

在URL的查询部分中使用“fields=”，后跟逗号分隔的属性名称列表。此后不会在响应中返回资

源的其他字段或属性。建议API支持此功能，以防它处理大对象，并且需要在受限制的带宽上工作。例

如：手机应用程序。

示例：GET/bics?fields=institution_name,address.city返回

{

"name""MyBankInc."

"address":{

"city":"London"

}

}

“OR”过滤器与“AND”过滤器的比较

简单的AND请求：为查询的每一段发送单独的调用，不同的调用可能包含重复。

简单的(X)OR请求：为查询的每一段发送单独的呼叫。如果第一个响应是否定的，那么发送第二

个响应等...

复杂的,嵌套的AND/(X)OR请求：在名为“q”的参数后面的URL中定义通用结构。

——使用“&”来表示AND

14

GB/TXXXXX—XXXX

——使用“|”来表示OR

——使用点表示法来命名作为分层嵌套资源结构的子字段的资源属性。例如：address.city

分页请求

推荐使用的最常用技术是使用limit来表示应在“页面”中返回的最大对象数，并使用offset来表

示页面的起始对象。

Limit是最大限制，因此例如最后返回的页面可以包含少于限制的元素个数。

这适用于所有简单的分页，并且易于应用程序开发人员使用。对于复杂情况（图形，动态更改集

合），可能会应用其他技术。

示例：orders?limit=25&offset=50

返回最多25个元素，从返回的订单列表中第一个元素之外的50号位置开始。在第一个元素索引为0

的编号列表中，返回对象索引为50到74。在第一个元素索引为1的编号列表中，返回对象索引为51到75。

实际上，HATEOAS是服务器在部分响应中指定哪些链接应该由客户端用于获取结果的其他页面的智

能方式。

9.1.8POST请求方法

使用POST有两种建议：创建资源，读取资源。

当GET方法受到如参数长度限制或安全要求的限制时，POST用于读取。使用POST进行读取时，不允

许使用URI查询参数，而需通过请求体将查询参数作为多形式数据内容类型传递。

表4POST请求用法示例

URI请求URI路径请求体请求头

定位器X

过滤器X

状态X

内容X

示例：通过GET和POST读取订单。

/orders?orderId=xxxx

POST/ordersHTTP/2.0

Conent-Type:application/x-www-form-urlencoded;charset=utf-8

Host:

orderId=xxxx

POST用于创建具有数据有效负载（包含幂等主键）的资源，作为xml或json内容请求。有关数据有

效负载语法，请参见第[12]章。

示例：使用幂等主键“orderId”来创建一个订单。

POST/ordersHTTP/2.0

Content-Type:

application/json;charset=utf-8

Host:

{

"orderId":"order0000000001"

"orderBody":{

"price":"xxx"

}

}

15

GB/TXXXXX—XXXX

9.1.9响应

对象和状态

对请求的正常回应是具有HTTP状态代码200-“OK”的HTTP响应，后面跟随着包含对象及其状态的表

示的响应体，可以是JSON或XML格式。

成功与错误

成功：当可以处理请求时，即可以返回“业务响应”。业务响应是对象和/或其状态的表示形式，

或者操作的结果（例如，资源的创建，或计算等）。在这种情况下，不会返回“错误”：HTTP状态代码

将是符合HTTP标准的任何成功2XX类响应，并且响应中不会出现“错误”块。

错误：当无法处理API请求时，没有业务响应：不返回对象及其状态的表示形式，也不返回任何操

作结果。而是返回一个错误元素：HTTP状态代码将在4xx范围或5xx范围内，并且响应中将出现“错误”

元素。

错误元素

值得注意的是，并非所有字段（如下所示）都是必需的，有些是可选项。

HTTP状态代码有时不足以传达有关错误的足够信息。此规范定义了适合此目的的简单JSON格式。它

们旨在由HTTPAPI重用，可以识别针对于他们需求的不同“问题类型”。因此，可以向API客户端通知

高级错误类（使用状态代码）和问题的细粒度细节（使用这些格式之一）。错误信息格式是

问题详细信息的规范模型是JSON对象。RFC7807将错误详细信息定义为“application/problem+

json”媒体类型。

问题详细信息对象可以包含以下成员：

——“type”（字符串）：对问题类型的简短的、人类可读的摘要。它不应该随着问题的发生而改变，

除非是为了本地化(例如，使用主动的内容协商)。

——“title”（字符串）：问题类型的简短的，人类可读的摘要。除了本地化的目的（例如，使

用主动内容协商）之外，它不应该从发生到问题的发生而改变。

——“status”（数字）：原始服务器为此问题发生而生成的HTTP状态代码（[RFC7231]）。

——“detail”（字符串）：特定于此问题发生的人类可读解释。

——“instance”（字符串）：标识问题特定事件的URI引用。如果取消引用，它可能会或可能

不会产生进一步的信息。

消费者应使用“type”字符串作为问题类型的主要标识符。“title”字符串是建议性的，仅包括

那些不了解URI语义且无法发现它们的用户（例如，离线日志分析）。消费者不应自动取消引用类型URI。

“status”成员（如果有）仅提供咨询，它传达了用于方便消费者的HTTP状态代码。生成器应在实

际HTTP响应中使用相同的状态代码，以确保不理解此格式的通用HTTP软件仍能正常运行。

消费者可以使用“status”成员来确定生成器使用的原始状态代码是什么，用于它已经被改变的地

方（例如，通过中间设备或高速缓存），和当消息体在没有HTTP信息的情况下持续存在的时候。通用HTTP

软件仍将使用HTTP状态代码。

“detail”成员（如果存在）应该专注于帮助客户解决问题，而不是提供调试信息。

示例：带有JSON问题详细信息的HTTP响应：

HTTP/1.1403Forbidden

Content-Type:application/problem+json

Content-Language:en

{

"type":"/probs/out-of-credit",

"title":"Youdonothaveenoughcredit.",

"detail":"Yourcurrentbalanceis30,butthatcosts50.",

"instance":"/account/12345/msgs/abc",

"balance":30,

16

GB/TXXXXX—XXXX

"account":["/account/12345","/account/67890"]

}

这里，信用缺失问题（由其类型URI标识）表示“标题”中403的原因，为“实例”提供特定问题发

生的参考，在“详细信息”中给出特定于事件的详细信息，并添加两个扩展名。“余额”表示帐户的余

额，“帐户”表示帐户可以充值的链接。

传达特定问题扩展的能力允许传达不止一个问题。例如：

HTTP/1.1400BadRequest

Content-Type:application/problem+json

Content-Language:en

{

"type":"/validation-error",

"title":"Yourrequestparametersdidn't",

validate.","invalid-params":[{

"name":"age",

"reason":"mustbeapositiveinteger"

},

{

"name":"color",

"reason":"mustbe'green','red'or'blue'"}

]

}

请注意，这要求每个子问题足够相似以使用相同的HTTP状态代码。如果不这样做，207（多状态）

[RFC4918]代码可用于封装多个状态消息。

分页请求响应

响应的每个页面都可能包含元数据，结构如下：

"page_header":{"total_count":x,"offset":y,"count":z},

响应将使用单独的元素page_header来指示有关分页的信息，其中包含以下数据：

——total_count表示所有页面中返回列表中可用对象的总数。这不是强制性的；

——count表示页面中的对象数。此值应与请求中的limit值相同，但不保证。例如，在最后一页

中，count可以低于请求中的limit值；

——offset表示页面的起始对象。该值应与请求中的offset值相同。

空列表

如果API调用搜索资源，它将返回与搜索条件匹配的多个资源的数组，如果未找到匹配的资源，则

该数组可以为空。在这种情况下，空数组不是错误。资源是正在访问的数组本身。返回数组的最佳做法

是标记出数组中有多少对象（或“记录”）-这称为元数据-以及结果记录列表。在空列表的情况下，

HTTP状态将是“成功”（HTTP'200-OK'），元数据将显示“total_count”=0，并且数组将是空数组

（JSON中的空数组）。

示例：

GET/orders

响应

{

"list_header":{"total_count":0,"offset":0,"count":0},

"orders":