共通性應用程式介面開放(Open API)規範(草案)

壹、目的 

　　本規範研析現行世界各國開放資料所採行之資料介接存取方式，比較國內各既有資料開放平臺及開放服務提供單位，並考量資料開放之應用情境，訂定共通性資料存取應用程式介面規範。

　　既有資料開放平臺及開放服務提供單位可依循本規範建置基本資料存取應用程式介面、或強化既有開放服務；並提供資料使用者一致性操作介面取得開放資料，以達 M2M (Machine to Machine)自動資料介接目的。 

貳、應用範圍 

　　本規範之共通性資料存取應用程式介面(以下簡稱 API)用於開放資料自動化介接，提供取得資料集詮釋資料、取得指定條件之資料集資料資源內容等功能。

　　各機關可根據本規範進行資料存取應用程式介面程式開發，以提供資料使用者或開發者一致性 API 取得或搜尋所需的資料集資料，有利資料集互通交換，加速開放資料加值應用與服務發展。

　　本規範制定之資料資源內容 API 適用於一般結構化資料內容(如XML、CSV、JSON)，其他相關特定資料格式(如 DOCX、PDF、SHP、KMZ)，則不在此應用範圍內。地理資訊系統常用之 KML 與GML，皆屬 XML 格式，故為一般結構化資料內容。

　　共通性資料存取應用程式介面主要提供一般結構化資料內容取得，不包括資料內容應用層面解析，如複雜數學邏輯運算篩選、應用領域所代表之意義判斷、欄位之間相關性等。 

參、名詞定義

　　本節列出本規範中，使用之名詞及其定義，提供文件閱讀之參考。 

1.      OpenAPI Swagger 2.0的規格，並準備向後兼容Swagger 3.0

• http://swagger.io/specification/

• Swagger 2.0比較算是"皮"，OData、GraphGL的才是實際的彈性Interface工具
• Swagger跟OData都有各自的validator.

2.      OData、GraphQL的橋接方式及相關規範

• OData https://zh.wikipedia.org/wiki/OData%E5%8D%94%E5%AE%9A
• 創始於2007年的微軟公司，是一個開源的協定，以簡單和標準的方法，建造或消除可查詢和可操作的RESTful API
• 
  

• https://www.npmjs.com/package/odata2openapi
• 橋接方式

• OData參考資料：（PTX）
• http://ptx.transportdata.tw/ptx/Download/%E5%85%AC%E5%85%B1%E9%81%8B%E8%BC%B8%E6%95%B4%E5%90%88%E8%B3%87%E8%A8%8A%E5%B9%B3%E5%8F%B0%E8%B3%87%E6%96%99%E6%9C%8D%E5%8B%99%E9%96%8B%E7%99%BC%E5%AF%A6%E4%BD%9C.pdf

• GraphQL

3.      API Discovery (3.8)

為了讓網站引用其API描述，建議在APIs.json內的header或in-line reference加入API鏈接關係，例如：

 * <link rel =“api”type =“application / apis + json”href =“https://example.com/apis.json”/>

整批匯入匯出功能(?)

參考網址：

• 資訊服務納入 Open API 標準之推動建議 https://talk.pdis.nat.gov.tw/t/open-api/17
• JSON for Linking Data http://json-ld.org/
• 驗證器參考 http://ptx.transportdata.tw/MOTC
• 私部門Open API應用情況(2012年) https://www.programmableweb.com/news/over-2000-apis-added-2011-social-telephony-open-government/2012/01/04

This pad text is synchronized as you type, so that everyone viewing this page sees the same text.  This allows you to collaborate seamlessly on documents!