金融服務中基于Web服務的應用程序編程接口技術規(guī)范

ICS03.060

A11

中華人民共和國國家標準

GB/TXXXXX—XXXX

金融服務中基于Web服務的應用程序接口

Web-service-basedApplicationProgrammingInterfaceinFinancialServices

（ISO/TS23029:2020）

征求意見稿

XXXX-XX-XX發(fā)布XXXX-XX-XX實施

GB/TXXXXX—XXXX

前言

本文件按照GB/T1.1-2020《標準化工作導則第1部分：標準化文件的結構和起草規(guī)則》的規(guī)則起

草。

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

本文件由中國外匯交易中心暨銀行間同業(yè)拆借中心提出。

本文件由全國金融標準化技術委員會（SAC/TC180）歸口。

本文件負責起草單位：中國外匯交易中心暨全國銀行間同業(yè)拆借中心。

本文件主要起草人：。

本文件為首次制定。

II

GB/TXXXXX—XXXX

金融服務中基于Web服務的應用程序接口

1范圍

本文件定義了API生態(tài)系統(tǒng)的框架、功能和協(xié)議，以實現(xiàn)在線同步交互。具體內容包括：

——定義了用于開發(fā)API的邏輯和技術分層方法，包括轉換規(guī)則，不包括特定的邏輯模型（例如

ISO20022模型），但作為指導，它們將在特定情景下被引用；

——主要是從RESTful設計的角度考慮，但也會考慮其他場景提供的架構樣式（如WebSocket和

Webhook）；

——定義了API的設計原則、基于Web服務的API規(guī)則、數(shù)據(jù)有效負載和版本控制；

——列出了與API設計的安全性、身份和注冊相關的注意事項。

本文件不適用于以下內容：

——金融服務中API實施的特定技術規(guī)范；

——基于ISO20022特定報文格式開發(fā)的JSONAPI，例如PAIN、CAMT、PACS；

——由特定法律框架定義或確定的技術規(guī)范。

2規(guī)范性引用文件

下列文件中的內容通過文中的規(guī)范性引用而構成本文件必不可少的條款。其中，注日期的引用文件，

僅該日期對應的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本

文件。

ISO20022-1金融服務—金融業(yè)通用報文方案—第1部分：元模型（Financialservices—

Universalfinancialindustrymessagescheme—Part1:Metamodel）

ISO20022-3金融服務—金融業(yè)通用報文方案—第3部分：建模導則（Financialservices—

Universalfinancialindustrymessagescheme—Part3:Modelling）

ISO20022-4金融服務—金融業(yè)通用報文方案—第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）

指一組明確定義的方法、函數(shù)、協(xié)議、事務或命令，應用程序軟件通過使用它和編程語言開發(fā)工具

來調用服務。API適用于不同類型的軟件，包括基于Web的系統(tǒng)。

3.2

超文本傳輸協(xié)議hypertexttransferprotocol（HTTP）

3

GB/TXXXXX—XXXX

指一種用于分布式、協(xié)作式和超媒體信息系統(tǒng)的應用層協(xié)議。超文本是一種結構化的文本,在包含

文本的節(jié)點之間使用邏輯鏈接(也叫超鏈接)。

3.3

冪等性idempotency

在計算機技術中，冪等性，也稱為冪等，是一個操作特征，這意味著如果多次調用該操作，不會產(chǎn)

生額外的影響。因為很難限制冗余訪問，所以冪等操作通常用于設計基于Web的系統(tǒng)。

3.4

JS對象簡譜javascriptobjectnotation（JSON）

指輕量級的、基于文本的數(shù)據(jù)格式。

3.5

表現(xiàn)層狀態(tài)轉換representationalstatetransfer（REST）

表現(xiàn)層狀態(tài)轉換，也稱為RESTful，是一個分布式超媒體系統(tǒng)的架構樣式，由RoyFielding在其2000

年所著的論文中提出。

3.6

資源路徑resourcepath

旨在指定與給定API請求相關的資源所在地址。

3.7

資源躍點resourcehop

指一個基于資源類型和標識符的資源定位器，資源路徑是一個或多個資源躍點的鏈。

3.8

結構化描述語言RESTfulAPIdescriptionlanguage

指用于提供RESTfulWebAPI的結構化描述的語言，該API對人工和自動化的機器處理都很有用。

3.9

簡單對象訪問協(xié)議simpleobjectaccessprotocol（SOAP）

指用于在計算機網(wǎng)絡中實現(xiàn)Web服務時交換結構化信息的一種協(xié)議規(guī)范。

3.10

網(wǎng)絡套接字websocket

指一個允許在受控環(huán)境中運行不受信任代碼的客戶端與已選擇通過該代碼進行通信的遠程主機之

間的雙向通信的協(xié)議。

3.11

網(wǎng)絡鉤子webhook

指由某些事件觸發(fā)的用戶定義的HTTP回調，例如將代碼推送到存儲庫或將評論發(fā)布到博客。

3.12

可擴展標記語言extensiblemarkuplanguage（XML）

可擴展標記語言，由W3C創(chuàng)建的數(shù)據(jù)格式標準。

4縮略語

以下縮略語適用于本文件。

URIUniformResourceIdentifier統(tǒng)一資源標識符

4

GB/TXXXXX—XXXX

HATEOASHypermediaastheengineofapplication超媒體即應用狀態(tài)引擎

state

SMTPSimpleMailTransferProtocol簡單郵件傳輸協(xié)議

JWTJsonwebtokenJsonweb令牌

5設計原則

本節(jié)介紹了開發(fā)WebAPI的原則。它涵蓋了在金融服務中開發(fā)API時應首先考慮的獨立設計和適用于

特定類型API的原則，并在WAPI樣式下進行了更詳細的討論。

5.1標準兼容性

WAPI主張盡可能使用ISO數(shù)據(jù)標準，并將其作為最佳選擇，以促進互操作性。

5.2可擴展性

API的設計應盡可能具有可擴展性，數(shù)據(jù)標準可能會更改，但API不會。這是為了確保它們的使用能

夠適應未來的用例或場景。

5.3不可否認性

不可否認性對WebAPI中的數(shù)據(jù)交換的有效性來說非常重要，它可提高待交換的數(shù)據(jù)的準確性。數(shù)

字簽名可以在API中使用。

5.4Web資源唯一標識符（ID字段）

Web資源應具有可用于標識資源的唯一標識符（例如：主鍵），這些唯一標識符用于構造URL/URI

以標識和尋址特定資源。

5.5冪等性

對于WebAPI，應預先考慮冪等性，這在WAPI樣式中有介紹。

5.6狀態(tài)

預先考慮需要哪個狀態(tài)。

6相關技術

本節(jié)對相關技術進行闡述，并提供其在金融服務中使用API的一些背景信息。它不包括上面所述的

術語和定義，也不包括如何處理該技術的具體指導，如下所述（WAPI樣式）。

6.1表現(xiàn)層狀態(tài)轉換（REST）和簡單對象訪問協(xié)議（SOAP）

REST和SOAP提供了訪問Web服務的方法，并且需要考慮同時使用。

6.1.1表現(xiàn)層狀態(tài)轉換（REST）

REST或RESTfulWeb服務提供了傳輸資源的表示狀態(tài)，并指定要在此資源上處理的操作方法（請參

閱術語和定義）。REST是最受歡迎的構建Web服務或定義WebAPI的方法，因為它簡單，并且與HTTP等現(xiàn)

有Internet標準兼容。

API通常使用REST，因為它更有效并且需要更少的處理。在大多數(shù)使用RESTfulAPI的金融場景中，

終端用戶向服務器發(fā)送消息，然后服務器快速響應。例如，在交易系統(tǒng)中下訂單或在賬戶上請求余額。

REST結構可用于實現(xiàn)這些通信請求或響應。具體可由以下六點來描述REST的結構特性:

——統(tǒng)一接口:統(tǒng)一接口約束定義了客戶端和服務器之間的接口。它簡化和解耦了REST結構，使每

個部分都能夠獨立擴展。

——無狀態(tài):一個客戶端可以向服務器發(fā)送多個請求;但是，每個請求都必須是獨立的，也就是說，

每個請求都必須包含所有必要的信息，以便服務器能夠理解它并相應地處理它。在這種情況下，

服務器不能保留關于客戶端狀態(tài)的任何信息。任何信息狀態(tài)都必須保留在客戶端上——比如會

5

GB/TXXXXX—XXXX

話。

——可緩存的:由于許多客戶端訪問相同的服務器，并且經(jīng)常請求相同的資源，因此有必要緩存這

些響應，以避免不必要的處理并顯著提高性能。

——客戶端-服務器。統(tǒng)一的接口將客戶機與服務器分開。這種分離的關注點意味著，例如，客戶

端不關注數(shù)據(jù)存儲，數(shù)據(jù)存儲仍然是每個服務器內部的，這樣客戶端代碼的可移植性就會提高。

服務器不關心用戶界面或用戶狀態(tài)，這樣服務器可以更簡單，可擴展性更強。只要不改變界面，

服務器和客戶端也可以獨立更換和開發(fā)。

——分層系統(tǒng):客戶端通常無法分辨它是直接連接到終端服務器，還是中間連接。通過啟用負載平

衡和提供共享緩存，中間服務器可以提高系統(tǒng)的可伸縮性。層還可以強制執(zhí)行安全策略

——代碼按需(可選):這個條件允許客戶按需運行一些代碼，也就是說，通過小程序或腳本將部分

服務器邏輯擴展到客戶端。因此，即使使用服務器提供完全相同的服務，不同的客戶也可能以

特定的方式行事。由于該項不是體系結構本身的一部分，因此被認為是可選的。它可以用于執(zhí)

行一些更有效或更快的客戶端服務。

6.1.2簡單對象訪問協(xié)議（SOAP）

SOAP是一種消息傳遞的協(xié)議規(guī)范，用于在計算機網(wǎng)絡的Web服務中交換結構化信息。它使用XML消息

格式，并通常使用HTTP或SMTP用于協(xié)商和傳輸消息。

SOAP允許在不同操作系統(tǒng)（例如Windows和Linux）上運行的進程使用XML進行通信。由于HTTP等Web

協(xié)議已在操作系統(tǒng)上安裝并運行，因此SOAP允許客戶端調用Web服務接收獨立于語言和平臺的響應。

6.2網(wǎng)絡套接字（WebSocket）和網(wǎng)絡鉤子（Webhook）

WebSocket和Webhook協(xié)議存在于REST無法滿足的場景中，例如支持未經(jīng)請求的響應。特別是：

——對于客戶端到客戶端的體系結構，可以使用Webhook；

——對于客戶端到服務器體系結構，可以使用WebSocket；

——用于任何類型的發(fā)布/訂閱實現(xiàn)。

6.2.1網(wǎng)絡套接字（WebSocket）

如RFC64551)中所述，WebSocket協(xié)議支持客戶端與遠程主機之間進行全雙工通信。此處所用的安全

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

該技術的目標是為基于瀏覽器的應用程序提供一種機制，該機制需要與不依賴于打開多個HTTP連接

的服務器進行雙向通信。在大規(guī)模數(shù)據(jù)傳輸或由服務器驅動的事件的情況下，WebSocket比HTTP表現(xiàn)更

好，例如市場數(shù)據(jù)分發(fā)和市場公告發(fā)布。其特征如下：

——大多數(shù)瀏覽器都支持WebSocket協(xié)議（IETFRFC6455），但客戶端可能是任意軟件代理。

——會話由協(xié)議升級的HTTP請求啟動。TLS握手用于校驗和驗證，并且密碼套件被啟用以確保隱

私和不可否認性。

——初始握手后，會話成為雙向異步消息傳遞協(xié)議。因為任何一方都可能推送未經(jīng)請求的消息，所

以不需要輪詢機制。

——定義了兩個子協(xié)議：文本消息（例如JSON或XML），以及二進制消息（例如，簡單的二進制

編碼）。如果需要，對等體可以支持多個子協(xié)議。其他子協(xié)議可以在IANA注冊，例如ISO20022

消息。

——WebSocket通過TCP分層。它繼承了其可靠性和流量控制功能。但是，WebSocket通過TCP流

構建消息。因此，應用程序無需關注框架。

——沒有會話協(xié)議標頭強加于應用程序消息。消息是自包含的，因此可以作為一個單元進行序列

化或轉發(fā)（與HTTP相反，其中語義信息分散在有效負載、URI和頭部上）。

——會話協(xié)議沒有提供將請求與響應相關聯(lián)的機制，因為它是事件驅動的協(xié)議而不是請求/響應。

事件的相關性將在具有事務ID等的應用層處執(zhí)行。

6.2.2網(wǎng)絡鉤子（Webhook）

1)/html/rfc6455

6

GB/TXXXXX—XXXX

Webhook有時被稱為“反向API”。Webhook是“用戶定義的HTTP回調”。它通?；谑录|發(fā)，例

如將代碼推送到存儲庫或將評論發(fā)布到博客。事件觸發(fā)時，源站點會對為webhook配置的URL發(fā)出HTTP

請求。用戶可以將它配置為使一個站點上的事件調用另一個站點上的行為。Webhook用途很多，常見用

途是使用持續(xù)集成系統(tǒng)觸發(fā)構建或通知錯誤跟蹤系統(tǒng)。由于它使用HTTP，因此無需添加新的基礎架構即

可將它集成到Web服務中。

6.3超文本傳輸協(xié)議（HTTP）

超文本傳輸協(xié)議（HTTP）是一種用于分布式、協(xié)作式和超媒體信息系統(tǒng)的應用層協(xié)議。超文本是結

構化文本，它使用包含文本的節(jié)點之間的邏輯鏈接（超鏈接）。HTTP是交換或傳輸超文本最常用的協(xié)議。

6.4JS對象簡譜（JSON）和可擴展標記語言（XML）

在Web通信場景中，最常用的兩種用于數(shù)據(jù)交換的結構化數(shù)據(jù)格式是XML和JSON[RFC82592)]。

6.4.1JS對象簡譜（JSON）

JSON是一種基于文本的輕量級數(shù)據(jù)格式，廣泛用于基于Web的通信，包括作為XML的替代品。

6.4.2可擴展標記語言（XML）

XML是由W3C3)創(chuàng)建的數(shù)據(jù)格式標準。

6.5內容協(xié)商

內容協(xié)商是指客戶端和服務器協(xié)商從服務器返回的內容樣式的機制。客戶端可以使用以下HTTP標頭

請求特定樣式的文檔：Accept、Accept-Language、Accept-Charset。它們分別指文檔的格式、文檔的

語言和文檔的字符集。

收到HTTP請求后，服務器必須查看Accept標頭以確定它是否可接受。如果不可接受，則服務器必須

返回HTTP406NotAcceptable狀態(tài)代碼。如果請求是可接受的，則服務器必須在Content-Type響應頭

中為請求附加正確的MIME類型。服務器可以選擇遵循瀏覽器的語言和字符集首選項以格式化響應。如果

服務器選擇遵循Accept-Language和Accept-Charset標頭，則使用的響應標頭應為Accept-Language標頭

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

6.6RESTfulAPI描述語言

RESTfulAPI描述語言是一種形式語言，旨在提供RESTfulWebAPI的結構化描述，該API對人工和

自動化機器處理都很有用。

RESTfulAPI的描述語言通常是中性的，與語言無關，與行業(yè)無關。它并沒有定義API本身，但對于

API生態(tài)系統(tǒng)的設計者、程序員和用戶非常有用，特別是在構建大規(guī)模的API時。本質上，RESTfulAPI

描述語言是一種軟件工程方法學，而不是一種計算機架構或通信技術。圍繞RESTfulAPI描述語言的社

區(qū)很活躍，而且情況仍在變化。到目前為止，這方面最活躍的項目是OpenAPI、RAML和APIBlueprint。

——OpenAPI規(guī)范

最初稱為Swagger規(guī)范，是一個用于描述、生產(chǎn)、消費和可視化RESTfulweb服務的機器可讀接口文

件的規(guī)范。自2016年起，它成為Linux基金會的開源協(xié)作項目，最新版本是3.0。

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

——RAML

RAML是一種基于yaml的語言，用于描述RESTfulapi。它提供了描述RESTfulapi或實際上是RESTful

api所需的所有信息。盡管RAML是基于RESTfulapi設計的，但它能夠描述那些不遵守REST的所有約束的

api(因此描述為“實際上是RESTful的”)。它鼓勵重用，支持發(fā)現(xiàn)和模式共享，并旨在基于優(yōu)點的最佳

實踐的出現(xiàn)。

URL:/

——API藍圖

2)/html/rfc8259

3)/html/rfc6455

7

GB/TXXXXX—XXXX

API藍圖是一種面向文檔的webAPI描述語言。API藍圖本質上是一組建立在用于描述webAPI的

Markdown語法之上的語義假設。

7命名規(guī)范

下表列出了WAPI應遵循的適用字符大小寫的約定。

表1API元素命名規(guī)范

API元素規(guī)則示例

盡管RFC2616指定HTTP標頭不區(qū)分大Accept-Charset

小寫，但在API規(guī)范中，最佳做法應該Train-Case是使用最廣泛的形式。

是對于所有標頭定義采用相同的字符單詞大寫并用連字符分隔(-)

HTTP標頭大小寫。

WWW-Authenticat

[RFC6648]應避免使用自定義專有的首字母縮略詞應大寫

“X-”類型的標頭e

最常用的形式是snake_case:單詞為小寫，用下劃

currency_code

線分隔(_)

查詢

lowerCamelCase:刪除空格和

參數(shù)

標點符號，除第一個單詞外，currencyCode

每個單詞的首字母大寫

資源路徑參見以下

最常用的形式是snake_case:單詞為小寫，用下劃

線分隔(_)currency_code

請求正文lowerCamelCase:刪除空格和

標點符號，除第一個單詞外，currencyCode

每個單詞的首字母大寫

以上是變量，用于數(shù)據(jù)類型UpperCammelCase的定義。

示例：

"country":{

數(shù)據(jù)類型CountryCode

"title":"Ctry,Country",

"description":"Countryoftheaddress.",

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

}

8資源路徑

資源路徑旨在指定與給定API請求相關的資源所在地址。

8.1資源躍點

此資源路徑是一個或多個資源躍點的鏈。每個資源躍點都基于以下組件構建：

——所有資源躍點都必須使用資源類型；

——除最后一個資源躍點外，資源標識符是必需的（見下文）

當在資源路徑中指定多個資源躍點時，假設除了第一個資源之外的每個資源在語義上鏈接到路徑中

的前一個資源。

躍點元素規(guī)則示例

8

GB/TXXXXX—XXXX

資源類型標準模式是使用復數(shù)形式的資源名稱來指定相同類型的資源集合(例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樣式

本節(jié)介紹如何設計和實現(xiàn)API的各個部分。盡可能為金融服務中的WebAPI提供決策依據(jù)。

本文檔涵蓋了三種WAPI樣式：REST、異步消息和服務推送。眾所周知，在金融服務中還有其他方法，

但這些被認為是覆蓋用例的主要例子。

9.1表現(xiàn)層狀態(tài)轉換（REST）

——對于需要在短時間內發(fā)送帶有回復的消息的金融場景，建議基于RESTfulapi構建，例如，在

交易系統(tǒng)中下訂單。

——REST是一種用于開發(fā)Web服務的架構樣式，它定義了一組約束，包括客戶端-服務器體系結構、

統(tǒng)一接口、無狀態(tài)等。

——與WAPI最相關的約束是統(tǒng)一接口和無狀態(tài)會話：

統(tǒng)一接口：統(tǒng)一接口約束定義了客戶端和服務器之間的接口。它簡化并解耦了REST架構，

使每個部分都能獨立擴展。RESTfulAPI通常使用HTTP方法GET，POST，PUT和DELETE

來構建統(tǒng)一的接口來操作資源。

9

GB/TXXXXX—XXXX

無狀態(tài)：一個客戶端可以向服務器發(fā)送多個請求;但是，每個請求都必須是獨立的，也就

是說，每個請求都必須包含所有必要的信息，以便服務器能夠理解它并相應地處理它。在

這種情況下，服務器不能保留關于客戶端狀態(tài)的任何信息。任何信息狀態(tài)都必須保留在客

戶端上——比如會話。

——REST樣式是分布式超媒體系統(tǒng)中架構元素的抽象，架構數(shù)據(jù)元素的本質和狀態(tài)是REST的一個

關鍵方面。與WAPI最相關的數(shù)據(jù)元素是資源和資源標識符（例如URI），表示和表示元數(shù)據(jù)

（例如，HTML，JSON，XML）。

——從客戶端和服務器的角度來看，使用REST的一個主要好處是，基于REST的交互，其使用的結

構是慣于使用互聯(lián)網(wǎng)超文本傳輸協(xié)議（HTTP）的任何人都熟悉的。換句話說，建議使用HTTP

來實現(xiàn)RESTfulWAPI。

——總之，設計和實現(xiàn)RESTfulWAPI的關鍵因素包括：統(tǒng)一接口，HTTP方法使用，無狀態(tài)，冪等

性，資源和資源標識符用法。

使用示例：訪問賬戶

圖1訪問賬戶的REST應用

9.1.1統(tǒng)一接口

資源標識符

請求中應使用URI作為資源標識符。交換的信息應該是資源的表示，使用特定語法表示（建議使用

XML或JSON），具體取決于請求和服務器的實現(xiàn)細節(jié)。

可操作資源

客戶端持有的資源表示法應該具有足夠的信息來修改或刪除服務器上的資源（如果允許）?？蛻舳?/p>

持有的資源表示形式應該具有足夠的信息，如果允許的話可以用來修改或刪除服務器上的資源。

10

GB/TXXXXX—XXXX

注釋

每條消息都應包含足夠的信息來描述如何處理它。例如，應使用網(wǎng)絡媒體類型來指定要調用的解析

器。響應還應明確指出其緩存能力。

超媒體即應用狀態(tài)引擎

客戶端應通過正文內容、查詢字符串參數(shù)、請求標頭和請求的URI（資源名稱）來提供狀態(tài)。服務

應通過正文內容、響應代碼和響應標頭向客戶提供狀態(tài)。

除了上面的描述之外，在必要時，HATEOAS還意味著鏈接包含在返回的正文（或標題）中，以提供

用于檢索對象本身的URI。

在這樣的體系結構中，每個響應將包含資源的后續(xù)表示形式。因此，進入“授權”狀態(tài)的響應還將

包含三個新的URI，指向三個狀態(tài)（授權，拒絕和接受）。

超媒體也可用于提供有關客戶端下一步能夠執(zhí)行的操作的信息：

——分頁功能；

——進一步操縱資源或子資源或鏈接資源。

當使用HATEOAS時，為了確保響應中不同部分的命名是一致的，它應該遵循v1.0的原

則：/about/。

9.1.2應用標準HTTP方法

使用指南

——使用標準的HTTP方法POST，GET，PUT和DELETE來操作資源，具有以下含義：POST=新建，

GET=讀取，DELETE=刪除，PUT（或PATCH）=更新。

——使用POST創(chuàng)建沒有任何指定資源標識符的資源。使用POST成功創(chuàng)建資源后，服務器的最佳實

踐是：

為新創(chuàng)建的資源分配標識符；

使用“201Created”和HTTP狀態(tài)以及新創(chuàng)建的資源的位置來回答客戶端。

——使用GET檢索使用其標識符指定的給定資源，或者可能通過某些搜索條件指定的一組資源。關

于GET請求的一些其他說明：

可以緩存GET請求；

GET請求保留在瀏覽器歷史記錄中；

GET請求可以加入書簽；

處理敏感數(shù)據(jù)時不要使用GET請求；

GET請求有長度限制。

——由于對GET的限制，在處理敏感數(shù)據(jù)或參數(shù)太多時允許使用POST進行讀取。

——使用DELETE刪除使用其標識符指定的給定資源，或者刪除可能通過某些搜索條件指定的一組

資源。

——使用PUT進行“完整”更新，即當整個資源位于PUT請求體時，將完全替換先前的資源。換句

話說，PUT必須是完整的資源更新，在PUT請求中應該發(fā)送所有屬性值以保證冪等性。

——當更新請求中僅存在資源的一個或幾個屬性時，使用PATCH進行部分更新，但不替換資源本身。

使用RFC7396作為PATCH的主體。這是最簡單，最直觀的方式，也是首選方式。盡管RFC7396

依賴于使用JSON作為語法，但其中指定的規(guī)則也可以在使用XML時應用。

示例：

表2應用標準HTTP方法示例

URLPOSTGETPUTPATCHDELETE

11

GB/TXXXXX—XXXX

/orders創(chuàng)建一個訂單列出訂單批量更換或創(chuàng)批量更新訂刪除所

(為創(chuàng)建訂單返建訂單4)單5)有訂單

回一個id)

/orders/00023569874錯誤6)獲取該訂如果存在，則替換如果存在，更新刪除該

1單細節(jié)訂單，否則創(chuàng)建訂訂單，或更新失訂單

單7)敗

9.1.3無狀態(tài)會話

無狀態(tài)會話表明，處理請求的必要狀態(tài)應由客戶端定義并包含在請求本身中，要么作為URI的一部

分，要么作為查詢字符串參數(shù)的一部分，要么作為正文或標題的一部分。在服務器進行處理之后，應將

適當?shù)臓顟B(tài)傳送回客戶端。

這與“會話”相反，后者在多個HTTP請求中維護狀態(tài)。在REST中，客戶端必須包含服務器的所有信

息以完成請求，如果該狀態(tài)必須跨越多個請求，則根據(jù)需要重新發(fā)送狀態(tài)。

狀態(tài)和資源都需要：

——狀態(tài)，或應用程序狀態(tài)，是服務器為完成當前會話或請求所需的數(shù)據(jù)請求而關心的狀態(tài)；

——資源或資源狀態(tài)是定義資源表示的數(shù)據(jù)——例如，存儲在數(shù)據(jù)庫中的數(shù)據(jù)。將應用程序狀態(tài)視

為因客戶端和每個請求而異的數(shù)據(jù)。另一方面，資源狀態(tài)在請求它的每個客戶端都是不變的。

9.1.4冪等性

通常，如果沒有額外的設計，WebAPI不應該是“讀取”應用程序的冪等?；谝韵略瓌t，建議Web

API“寫入”應用程序是冪等的：

——建議用于創(chuàng)建，更新或刪除資源的API是冪等的。此功能的目的是允許API用戶重試因超時或

意外錯誤而失敗的API請求；

——對于可能具有破壞性的操作，建議在API請求中實現(xiàn)冪等性主鍵；

——建議API的用戶在使用相同的冪等主鍵時不應該更改請求體，如果API用戶更改了請求正文，

則API提供程序不會修改結束資源；

——如果API請求者已收到具有相同主鍵的第一個請求，則應該將請求視為冪等的；

——如果請求成功，API提供商應該以資源的當前狀態(tài)響應請求，API提供程序可以使用消息簽名

（如果已實現(xiàn)）以及冪等主鍵來確保請求正文未更改。

9.1.5統(tǒng)一資源標識符的組成

4)在替換的情況下，有效資源的ID不能在有效載荷中提及（由應該替換或放在正文中）。

5)批量修補程序是批量更新資源的危險且不推薦的方法。

6)'POST'是用于創(chuàng)建尚不存在的資源。因此，對現(xiàn)有資源執(zhí)行POST會被視為錯誤。除非POST被PUT或PATCH覆

蓋。

7)讓客戶端創(chuàng)建資源ID是不好的做法。始終應該是由服務器來創(chuàng)建。

12

GB/TXXXXX—XXXX

圖2URI的組成

resource_path可以包括多個適用的資源，并伴有資源ID。通常URL不包含動詞，因為它們是基于資

源路徑的。

在Type，Issuer，Version概念中，URI可以通過定義{service}的方式來反映這一點，即反映Type

（whatIcall）和Issuer（whoprovidedthecall）。

示例：/refdata/v1/bics

9.1.6處理資源之間的關聯(lián)

公開URI路徑中的資源之間的關聯(lián)關系。但保持URI中的關系最小化，通常保持主鍵和所受影響的資

源的關聯(lián)就足夠了。

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

含義：“獲取BICPVRBRU4VXXX的所有SSI”，其中BICPVRBRU4VXXX被當做主鍵。

9.1.7請求參數(shù)用法

總則

請求中可能有各種類型的“參數(shù)”：

——定位器（資源標識符或特定操作）；

——過濾器（提供搜索，排序或限制結果的參數(shù)）；

——內容（要存儲的數(shù)據(jù)）。

由不同的占位符放置這些參數(shù)：

——URI查詢參數(shù)（URI后面的“?”問號部分）；

——URI路徑（URI后面的主機名或“完全限定域名”部分，以及“？”問號前面的部分）；

——HTTP請求正文；

——HTTP請求頭。

表3請求參數(shù)用法示例

URI請求URI路徑請求體請求頭

定位器X

過濾器X

狀態(tài)X

內容X

狀態(tài)

狀態(tài)在標題中設置，具體取決于狀態(tài)信息的類型。

13

GB/TXXXXX—XXXX

內容

內容只有一個所處位置，即請求體，它可以是有效負載/正文內容（XML或JSON），也可以是多部分

/表單數(shù)據(jù)請求。資源的內容應僅在正文中，而不是其他位置，例如標題。

資源過濾器

定位器屬于URL路徑。

示例：/bics/CITIUS33

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

過濾器放在查詢字符串中，因為雖然它們是獲取正確數(shù)據(jù)的一部分，但它們只是返回定位器返回內

容的子集。

有兩個例外，即定位器和過濾器可以進入HTTP請求體而不是URI：

——當URL的長度超過需要處理這些URL的最大長度（2K）時；

——當定位器或過濾器中的信息需要加密時，這些通常會放在URL中，但URL往往以未加密的形式

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

對于如果API需要支持這兩種特殊情況，則允許使用POST而不是GET，在POST的URI查詢部分使用

method=GET，并且使用包含URI查詢部分的POST主體會出現(xiàn)在正常的GET中。

屬性與搜索標準

將資源屬性和搜索條件放在“？”后面。

區(qū)分資源與其屬性之間的關系。通常兩個資源之間的關系通過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：當其地址所在國家/地區(qū)為比利時或德國時，返回bics。

過濾器

減少每個資源返回的屬性列表（過濾）。

在URL的查詢部分中使用“fields=”，后跟逗號分隔的屬性名稱列表。此后不會在響應中返回資

源的其他字段或屬性。建議API支持此功能，以防它處理大對象，并且需要在受限制的帶寬上工作。例

如：手機應用程序。

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

{

"name""MyBankInc."

"address":{

"city":"London"

}

}

“OR”過濾器與“AND”過濾器的比較

簡單的AND請求：為查詢的每一段發(fā)送單獨的調用，不同的調用可能包含重復。

簡單的(X)OR請求：為查詢的每一段發(fā)送單獨的呼叫。如果第一個響應是否定的，那么發(fā)送第二

個響應等...

復雜的,嵌套的AND/(X)OR請求：在名為“q”的參數(shù)后面的URL中定義通用結構。

——使用“&”來表示AND

14

GB/TXXXXX—XXXX

——使用“|”來表示OR

——使用點表示法來命名作為分層嵌套資源結構的子字段的資源屬性。例如：address.city

分頁請求

推薦使用的最常用技術是使用limit來表示應在“頁面”中返回的最大對象數(shù)，并使用offset來表

示頁面的起始對象。

Limit是最大限制，因此例如最后返回的頁面可以包含少于限制的元素個數(shù)。

這適用于所有簡單的分頁，并且易于應用程序開發(fā)人員使用。對于復雜情況（圖形，動態(tài)更改集

合），可能會應用其他技術。

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

返回最多25個元素，從返回的訂單列表中第一個元素之外的50號位置開始。在第一個元素索引為0

的編號列表中，返回對象索引為50到74。在第一個元素索引為1的編號列表中，返回對象索引為51到75。

實際上，HATEOAS是服務器在部分響應中指定哪些鏈接應該由客戶端用于獲取結果的其他頁面的智

能方式。

9.1.8POST請求方法

使用POST有兩種建議：創(chuàng)建資源，讀取資源。

當GET方法受到如參數(shù)長度限制或安全要求的限制時，POST用于讀取。使用POST進行讀取時，不允

許使用URI查詢參數(shù)，而需通過請求體將查詢參數(shù)作為多形式數(shù)據(jù)內容類型傳遞。

表4POST請求用法示例

URI請求URI路徑請求體請求頭

定位器X

過濾器X

狀態(tài)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用于創(chuàng)建具有數(shù)據(jù)有效負載（包含冪等主鍵）的資源，作為xml或json內容請求。有關數(shù)據(jù)有

效負載語法，請參見第[12]章。

示例：使用冪等主鍵“orderId”來創(chuàng)建一個訂單。

POST/ordersHTTP/2.0

Content-Type:

application/json;charset=utf-8

Host:

{

"orderId":"order0000000001"

"orderBody":{

"price":"xxx"

}

}

15

GB/TXXXXX—XXXX

9.1.9響應

對象和狀態(tài)

對請求的正?；貞蔷哂蠬TTP狀態(tài)代碼200-“OK”的HTTP響應，后面跟隨著包含對象及其狀態(tài)的表

示的響應體，可以是JSON或XML格式。

成功與錯誤

成功：當可以處理請求時，即可以返回“業(yè)務響應”。業(yè)務響應是對象和/或其狀態(tài)的表示形式，

或者操作的結果（例如，資源的創(chuàng)建，或計算等）。在這種情況下，不會返回“錯誤”：HTTP狀態(tài)代碼

將是符合HTTP標準的任何成功2XX類響應，并且響應中不會出現(xiàn)“錯誤”塊。

錯誤：當無法處理API請求時，沒有業(yè)務響應：不返回對象及其狀態(tài)的表示形式，也不返回任何操

作結果。而是返回一個錯誤元素：HTTP狀態(tài)代碼將在4xx范圍或5xx范圍內，并且響應中將出現(xiàn)“錯誤”

元素。

錯誤元素

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

HTTP狀態(tài)代碼有時不足以傳達有關錯誤的足夠信息。此規(guī)范定義了適合此目的的簡單JSON格式。它

們旨在由HTTPAPI重用，可以識別針對于他們需求的不同“問題類型”。因此，可以向API客戶端通知

高級錯誤類（使用狀態(tài)代碼）和問題的細粒度細節(jié)（使用這些格式之一）。錯誤信息格式是

問題詳細信息的規(guī)范模型是JSON對象。RFC7807將錯誤詳細信息定義為“application/problem+

json”媒體類型。

問題詳細信息對象可以包含以下成員：

——“type”（字符串）：對問題類型的簡短的、人類可讀的摘要。它不應該隨著問題的發(fā)生而改變，

除非是為了本地化(例如，使用主動的內容協(xié)商)。

——“title”（字符串）：問題類型的簡短的，人類可讀的摘要。除了本地化的目的（例如，使

用主動內容協(xié)商）之外，它不應該從發(fā)生到問題的發(fā)生而改變。

——“status”（數(shù)字）：原始服務器為此問題發(fā)生而生成的HTTP狀態(tài)代碼（[RFC7231]）。

——“detail”（字符串）：特定于此問題發(fā)生的人類可讀解釋。

——“instance”（字符串）：標識問題特定事件的URI引用。如果取消引用，它可能會或可能

不會產(chǎn)生進一步的信息。

消費者應使用“type”字符串作為問題類型的主要標識符。“title”字符串是建議性的，僅包括

那些不了解URI語義且無法發(fā)現(xiàn)它們的用戶（例如，離線日志分析）。消費者不應自動取消引用類型URI。

“status”成員（如果有）僅提供咨詢，它傳達了用于方便消費者的HTTP狀態(tài)代碼。生成器應在實

際HTTP響應中使用相同的狀態(tài)代碼，以確保不理解此格式的通用HTTP軟件仍能正常運行。

消費者可以使用“status”成員來確定生成器使用的原始狀態(tài)代碼是什么，用于它已經(jīng)被改變的地

方（例如，通過中間設備或高速緩存），和當消息體在沒有HTTP信息的情況下持續(xù)存在的時候。通用HTTP

軟件仍將使用HTTP狀態(tài)代碼。

“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的原因，為“實例”提供特定問題發(fā)

生的參考，在“詳細信息”中給出特定于事件的詳細信息，并添加兩個擴展名?！坝囝~”表示帳戶的余

額，“帳戶”表示帳戶可以充值的鏈接。

傳達特定問題擴展的能力允許傳達不止一個問題。例如：

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狀態(tài)代碼。如果不這樣做，207（多狀態(tài)）

[RFC4918]代碼可用于封裝多個狀態(tài)消息。

分頁請求響應

響應的每個頁面都可能包含元數(shù)據(jù)，結構如下：

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

響應將使用單獨的元素page_header來指示有關分頁的信息，其中包含以下數(shù)據(jù)：

——total_count表示所有頁面中返回列表中可用對象的總數(shù)。這不是強制性的；

——count表示頁面中的對象數(shù)。此值應與請求中的limit值相同，但不保證。例如，在最后一頁

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

——offset表示頁面的起始對象。該值應與請求中的offset值相同。

空列表

如果API調用搜索資源，它將返回與搜索條件匹配的多個資源的數(shù)組，如果未找到匹配的資源，則

該數(shù)組可以為空。在這種情況下，空數(shù)組不是錯誤。資源是正在訪問的數(shù)組本身。返回數(shù)組的最佳做法

是標記出數(shù)組中有多少對象（或“記錄”）-這稱為元數(shù)據(jù)-以及結果記錄列表。在空列表的情況下，

HTTP狀態(tài)將是“成功”（HTTP'200-OK'），元數(shù)據(jù)將顯示“total_count”=0，并且數(shù)組將是空數(shù)組

（JSON中的空數(shù)組）。

示例：

GET/orders

響應

{

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

"orders":