O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

共通性應用程式介面規範

738 visualizações

Publicada em

依國家發展委員會106年7月3日發資字第1061501003號函辦理,自即日起生效。

另參見工程會資訊服務採購契約範本修正明細對照1060713( http://www.pcc.gov.tw/pccap2/FMGRfrontend/DownloadQuoteFile.do?fileCode=F2017070048 ):

第二條 履約標的
(四)履約標的涉及共通性應用程式介面開發或整合者,應依國家發展委員會訂定之「共通性應用程式介面規範」辦理。

依國家發展委員會 105 年 11 月 21 日發資字第 1051501554 號函建議及本會 106 年 6 月 5 日召開「研商資訊服務採購契約範本(草案)」會議結論,增列第 4 款,將共通性應用程式介面納為履約標的之一環,以提供資料使用者一致性操作介面取得政府資料,避免因介接對象不同而需個別開發程式,影響資料交換,並達成機器與機器間(machine to machine)自動資料介接目的。

第十六條 權利及責任
(三)智慧財產權
6.廠商依本契約提供機關服務時,如使用開源軟體,應依該開源軟體之授權範圍,授權機關利用,並以執行檔及原始碼共同提供之方式交付予機關使用,廠商並應交付開源軟體清單 (包括但不限於:開源專案名稱、出處資訊、原始著作權利聲明、免責聲明、開源授權條款標示與全文)。

新增第 3 款第 6 目,約定廠商如使用開源軟體 (open source software),由廠商依該軟體授權範圍,授權機關利用,並訂明廠商交付開源軟體執行檔、原始碼與相關授權文件之義務, 以利廠商與機關確認有無符合授權及授權內容。

Publicada em: Governo e ONGs
  • Seja o primeiro a comentar

  • Seja a primeira pessoa a gostar disto

共通性應用程式介面規範

  1. 1. 共通性應用程式介面規範 國家發展委員會 中華民國 106 年 6 月
  2. 2. 目  錄 壹、目的.........................................................................................1 貳、應用範圍.................................................................................1 參、名詞定義.................................................................................1 肆、規範準則.................................................................................3 一、符合 OAS 標準之 API 說明文件.....................................................3 (一)OAS 標準設計重點............................................................................................3 (二)OAS 標準驗證方式............................................................................................4 二、RESTful API 語法規則....................................................................5 三、API 版本描述方式...........................................................................6 四、API Discovery...................................................................................6 附錄.................................................................................................7 附錄 1-OpenAPI Specification 實際案例解析......................................7 附錄 2-OpenAPI Specification 中文摘要譯本....................................12
  3. 3. 壹、目的 原 104 年 7 月頒訂「共通性資料存取應用程式介面規範」目的為提供 各資料開放平臺使用者以一致性應用程式介面 ( Application Programming Interface, 以下簡稱 API )取得資料。以 RESTful 風格為主要基礎,訂定應 用程式介面的呼叫方式、語法規則及所提供的介面類型等項目,以達自動 資料介接目標。 為擴大政府資訊服務效益,並保有各系統 API 開發彈性,爰導入國際 Open API Initiative 組織之 OpenAPI Specification (以下簡稱 OAS) 標準,藉 由一致性之描述方法,提供機器可讀之標準格式 API 說明文件,以大幅降 低資料存取、API 調整以及維護等門檻,進而提升政府資訊效能。 貳、應用範圍 本規範適用於可資料讀取/寫入之應用程式介面(API),為使 API 具有 共通性之特性,各機關採 API 對外提供服務或其傳輸資料內容不涉及機敏 性之 API,請提供符合 OAS 標準之說明文件。不論該 API 所使用之授權及 存取限制,均可採 OAS 標準進行描述。 參、名詞定義 英文名稱 中文名稱 定義 API (Application Programming Interface) 應用程式介面 為「『電腦作業系統 (Operating system)』或 『程式函式庫』提供給應 用程式呼叫使用的程式碼 」。其主要目的是讓應用 程式開發人員得以呼叫一 組常式功能,而無須考慮 其底層的原始碼為何、或 理解其內部工作機制的細 節。API 本身是抽象的,它 1
  4. 4. 僅定義了一個介面,而不 涉及應用程式在實際實現 過程中的具體操作。 REST 含狀態傳輸 全名為 Representational State Transfer,是一種軟體 架構設計風格。資源由 URI 指定,對資源的操作包括 取得、創建、修改和刪除 資源,這些操作正好對應 HTTP 協議提供之 GET、POST、PUT 和 DELETE 方法。 RESTful 含狀態傳輸的 Web 服務 是一個使用 HTTP 並遵循 REST 原則,以 URL 定位 資源,根據 HTTP 內容指 示操作動作與回應訊息。 JSON - 一種常見的輕量級資料交 換格式 YAML - 一個可讀性高,用來表達 資料序列的格式 SRU (Service Root URL) 服務根網址 描述平臺上提供各類別應 用服務之網址。 Resource Path 資源路徑 接續於服務根網址後,指 定某一資料集之資料資源 路徑 Query Options 查詢選項 接續於資源路徑後,針對 某一應用服務指定某一資 料集之資源項目,表達所 欲取得資料的範圍或查詢 的條件 Metadata 詮釋資料 描述資料的資料 M2M (Machine to Machine) 機器與機器間資料交換 機器中的應用系統,已設 定好定期呼叫機制與呼叫 API 方式,定期透過網際網 路直接呼叫資料開放平臺 提供之 API,以系統介接自 動取得特定資料。 2
  5. 5. 肆、規範準則 本規範之 API 設計主要依循共通性、輕便性及標準化準則。 ● 共通性:參採 Open API Initiative 組織之 OpenAPI Specification 標準, 作為 API 說明文件之一致標準。 ● 輕便性:參考現階段及未來趨勢之 API 呼叫方式,採用 RESTful 風格 API。 ● 標準化:參考國際通用 W3C 相關標準(如 URI、HTTP 等)及 OData.org 相關規範訂定之。 一、符合 OAS 標準之 API 說明文件 為實現共通性應用程式介面,API 開發應提供符合 OAS 標準1 之一致 性描述方法,提供機器可讀之標準格式 API 說明文件。 提供 OAS 實際案例解析如附錄 1,並提供 OAS 標準之中文摘要譯本 如附錄 2 供參。 (一)OAS 標準設計重點 ● 符合 OAS 標準之 API 說明文件(以下簡稱 OAS 文件)原則上由單一檔 案製成。 ● OAS 文件需以 JSON 或 YAML 檔案格式呈現(API 本身的輸入和回 傳值以及其他內容格式則未限制),並建議將 API 說明文件命名為 openapi.json 或 openapi.yaml。 ● OAS 文件之基本資料類型是依據 JSON Schema Specification Wright Draft 00 支援的類型訂定。其架構基於根物件 OpenAPI Object 展開, 物件具備各自的固定欄位(Fixed Fields),各欄位之類型(Type)則須符 合基本類別或物件定義。 以下摘要 OpenAPI Object 之固定欄位說明如下: 1 OAI 官方正式發布 OAS 版本:https://github.com/OAI/OpenAPI-Specification/tree/master/versions 3
  6. 6. 欄位名稱 Field Name 類型 Type 描述 Description openapi string 必填,這字串必須載明該文件所使用的 OpenAPI Specification 版本。這個 openapi 欄位應該要讓使 用者可藉由工具直譯其版本。該欄位與 API info 版本 號無關。 info Info Object 必填,提供這份 API 的詮釋資料。如有需要,這詮釋 資料亦可由使用者所使用。 servers [Server Object] 伺服器物件,可提供至目標伺服器之連結資訊。若未 提供該欄位,或為空陣列,則伺服器欄位之預設 URL 將會是根目錄"/"。 paths Paths Object 必填,記載這份 API 的功能操作及可用路徑。 components Components Object 用於記載保存於各種 schema 之元素。 security [Security Requirement Object] 宣告其可跨用於整份 API 之安全機制。其清單內包含 可供使用的 security requirement objects。僅需有一項 security requirement objects 滿足授權需求即可。可藉 由個別操作覆蓋此定義。 tags [Tag Object] 本標準於附加詮釋資料所使用的標籤清單。標籤順序 可被分析工具所解析。並非所有 Operation Object 所使 用的標籤都必須被宣告,未被宣告之標籤可被隨機地 或邏輯性地組織起來。清單中每個標籤名稱都必得是 獨一無二的。 (二)OAS 標準驗證方式 API 開發人員可透過 Open API Initiative 所提供之官方驗證工具2 ,對 OAS 文件內容進行檢測,若檢測結果無錯誤訊息且其顯示內容符合機關之 專案需求,可視為通過驗證。 2 OAI 提供之第三方驗證器,其驗證結果僅供參考: https://github.com/OAI/OpenAPI- Specification/blob/OpenAPI.next/IMPLEMENTATIONS.md 4
  7. 7. 二、RESTful API 語法規則 以政府資料開放平臺(data.gov.tw)為例,規劃 REST Web API,讓資 料使用者可以 HTTP GET 方式,取得政府資料開放平臺之資料,API 呼叫 回傳內容格式則以 JSON 為主,若 API 輸出內容格式為 JSON,則 HTTP header Content-Type 為 application/json。 服務路徑 URL 分為服務根網址(Service Root URL,簡稱 SRU)、資源 路徑(Resource Path)和查詢選項(Query Options): ● 服務根網址:平臺上提供該類別應用服務之網址。 ● 資源路徑:接續於 SRU 後,以指定某一資源項目路徑名稱。 ● 查詢選項:接續於資源路徑後,針對某一應用服務,指定所欲取得資 料之範圍或查詢之條件。 圖-1 URL 結構 依照上述 URL 結構定義,下圖以取得一資料集之資料資源內容 URL 為例。 http://data.gov.tw/api/ __________________/ | service root URL http://data.gov.tw/api/rest/datastore/355000000I-000003-001?limit=20&sort=County __________________/ ________________________________/ __________________/ | | | service root URL resource path query options 圖-2 URL 結構範例說明 5
  8. 8. 三、API 版本描述方式 因 API 規格或實作可能有版本之演進,故如有需要描述版本資訊應於 服務根網址(Service Root URL)說明,如下圖。版本資訊格式建議使用 v1、v2、v3,不建議使用 v-1.1、v1.2、1.3。 http://data.gov.tw/api/v1/rest/datastore/355000000I-000003-001?limit=20&sort=County ____________________/ ________________________________/ __________________/ | | | service root URL resource path query options 圖-3 含有版本資訊 URL 結構範例說明 四、API Discovery 如機關所提供之 API 可供外界所查詢,建議可於首頁 html 文件或者是 首頁的 Web 服務的 header 加入 API 鏈接關係,例如: <link rel =“api”type =“application / apis + json”href =“https://example.com/apis.json”/> APIs.json 並非 OAS 標準的一部份,而是一個機器可讀的 sitemap 概念 ,可將該網站所有使用到的 API 進行列示。 6
  9. 9. 附錄 附錄 1-OpenAPI Specification 實際案例解析 (一)JSON 格式-以「交通部公共運輸整合資訊流通服務平臺」為例 該規範已建立符合 Swagger (OAS 2.0)規範之 JSON 格式說明文件 (網路 位址:http://ptx.transportdata.tw/MOTC/API/Main/docs/v2 ),以下提供已 轉換至 OAS3 之 JSON 與 YAML 格式比對摘要: ● OpenAPI 欄位:版本描述。 JSON 格式 YAML 格式 { "openapi": "3.0.0-rc2", openapi: 3.0.0-rc2 ● server 欄位:路徑描述。 JSON 格式 YAML 格式 "servers": [ { "url": "http://ptx.transportdata.tw/MOTC" } ], servers: - url: http://ptx.transportdata.tw/MOTC ● info 欄位:該 API 之基本詮釋資料。 JSON 格式 YAML 格式 "info": { "version": "v2", "title": "MOTC Transport API V2", "description": "</div>n <div class="info_description markdown">資 料服務開發實作參考手冊:<a href= http://ptx.transportdata.tw/ptx/Downloa d/公共運輸整合資訊平台資料服務開發實作.pdf > 請點我</a><br>公車動態使用注意事項:<a href= http://ptx.transportdata.tw/ptx/Downloa d/交通部公共運輸整合資訊流通服務_公車動態預估 到站 N1 資料使用注意事項.pptx >請點我 </a><br>資料服務使用注意事項:<a href= http://ptx.transportdata.tw/ptx/Downloa d/資料服務使用注意事項(Readme)-v1.pdf >請點 info: version: v2 title: MOTC Transport API V2 description: |- </div> <div class="info_description markdown">資料服務開發實作參考手冊:<a href= http://ptx.transportdata.tw/ptx/Downloa d/公共運輸整合資訊平台資料服務開發實作.pdf > 請點我</a><br>公車動態使用注意事項:<a href= http://ptx.transportdata.tw/ptx/Downloa d/交通部公共運輸整合資訊流通服務_公車動態預估 到站 N1 資料使用注意事項.pptx >請點我 </a><br>資料服務使用注意事項:<a href= http://ptx.transportdata.tw/ptx/Downloa 7
  10. 10. 我</a><br>API URI Convention 文件說明:<a href= http://ptx.transportdata.tw/ptx/Downloa d/API_URI_Convention 文件_v1.pdf >請點我< /a>" }, d/資料服務使用注意事項(Readme)-v1.pdf >請點 我</a><br>API URI Convention 文件說明:<a href= http://ptx.transportdata.tw/ptx/Downloa d/API_URI_Convention 文件_v1.pdf >請點我< /a> ● paths 欄位:該 API 各項功能之呼叫路徑,可與 server 欄位中的路徑結合 為完整網址,並提供該項 API 之各項欄位、類別定義,以及範例說明。 (本案例僅摘要「取得指定[縣市]的公車動態定時資料(A1)」功能) JSON 格式 YAML 格式 "paths": { "/v2/Bus/RealTimeByFrequency/City/{City}": { "get": { "tags": [ "CityBusApi" ], "summary": "取得指定[縣市]的公車動態定時資 料(A1)", "description": "市區公車之定時資料(A1)", "operationId": "CityBusApi_RealTimeByFrequency", "parameters": [ { "name": "City", "in": "path", "description": "欲查詢縣市", "required": true, "schema": { "type": "string", "enum": [ { "Text": "臺北市", "Value": "Taipei" }, { "Text": "新北市", "Value": "NewTaipei" }, { "Text": "桃園市", "Value": "Taoyuan" }, { "Text": "臺中市", "Value": "Taichung" }, { "Text": "臺南市", "Value": "Tainan" }, { "Text": "高雄市", paths: '/v2/Bus/RealTimeByFrequency/City/ {City}': get: tags: - CityBusApi summary: '取得指定[縣市]的公車動態定時 資料(A1)' description: 市區公車之定時資料(A1) operationId: CityBusApi_RealTimeByFrequency parameters: - name: City in: path description: 欲查詢縣市 required: true schema: type: string enum: - Text: 臺北市 Value: Taipei - Text: 新北市 Value: NewTaipei - Text: 桃園市 Value: Taoyuan - Text: 臺中市 Value: Taichung - Text: 臺南市 Value: Tainan - Text: 高雄市 Value: Kaohsiung - Text: 基隆市 Value: Keelung - Text: 新竹市 Value: Hsinchu - Text: 新竹縣 Value: HsinchuCounty - Text: 苗栗縣 Value: MiaoliCounty - Text: 彰化縣 Value: ChanghuaCounty - Text: 南投縣 Value: NantouCounty 8
  11. 11. "Value": "Kaohsiung" }, { "Text": "基隆市", "Value": "Keelung" }, { "Text": "新竹市", "Value": "Hsinchu" }, { "Text": "新竹縣", "Value": "HsinchuCounty" }, { "Text": "苗栗縣", "Value": "MiaoliCounty" }, { "Text": "彰化縣", "Value": "ChanghuaCounty" }, { "Text": "南投縣", "Value": "NantouCounty" }, { "Text": "雲林縣", "Value": "YunlinCounty" }, { "Text": "嘉義縣", "Value": "ChiayiCounty" }, { "Text": "嘉義市", "Value": "Chiayi" }, { "Text": "屏東縣", "Value": "PingtungCounty" }, { "Text": "宜蘭縣", "Value": "YilanCounty" }, { "Text": "花蓮縣", "Value": "HualienCounty" }, { "Text": "臺東縣", "Value": "TaitungCounty" }, { "Text": "金門縣", "Value": "KinmenCounty" }, { - Text: 雲林縣 Value: YunlinCounty - Text: 嘉義縣 Value: ChiayiCounty - Text: 嘉義市 Value: Chiayi - Text: 屏東縣 Value: PingtungCounty - Text: 宜蘭縣 Value: YilanCounty - Text: 花蓮縣 Value: HualienCounty - Text: 臺東縣 Value: TaitungCounty - Text: 金門縣 Value: KinmenCounty - Text: 澎湖縣 Value: PenghuCounty - Text: 連江縣 Value: LienchiangCounty - Text: 新北市(雙北雲) Value: TaipeiCloud - name: ticket in: query description: 可透過 Account/Login API 取得,預設為 guest 的 ticket required: false schema: type: string - name: $select in: query description: 挑選 schema: type: string - name: $filter in: query description: 過濾 schema: type: string - name: $orderby in: query description: 排序 schema: type: string - name: $top in: query description: 取前幾筆 schema: type: string default: 30 - name: $skip in: query description: 跳過前幾筆 schema: type: string - name: $format in: query description: 指定來源格式 9
  12. 12. "Text": "澎湖縣", "Value": "PenghuCounty" }, { "Text": "連江縣", "Value": "LienchiangCounty" }, { "Text": "新北市(雙北雲)", "Value": "TaipeiCloud" } ] } }, { "name": "ticket", "in": "query", "description": "可透過 Account/Login API 取得,預設為 guest 的 ticket", "required": false, "schema": { "type": "string" } }, { "name": "$select", "in": "query", "description": "挑選", "schema": { "type": "string" } }, { "name": "$filter", "in": "query", "description": "過濾", "schema": { "type": "string" } }, { "name": "$orderby", "in": "query", "description": "排序", "schema": { "type": "string" } }, { "name": "$top", "in": "query", "description": "取前幾筆", "schema": { "type": "string", "default": 30 } }, { required: true schema: type: string enum: - Text: JSON Value: JSON - Text: XML Value: XML responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/' text/json: schema: type: array items: $ref: '#/components/schemas/' deprecated: false 10
  13. 13. "name": "$skip", "in": "query", "description": "跳過前幾筆", "schema": { "type": "string" } }, { "name": "$format", "in": "query", "description": "指定來源格式", "required": true, "schema": { "type": "string", "enum": [ { "Text": "JSON", "Value": "JSON" }, { "Text": "XML", "Value": "XML" } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/" } } } } } }, "deprecated": false } }, 11
  14. 14. 附錄 2-OpenAPI Specification 中文摘要譯本 12

×