OAS

提供符合 OAS 標準之說明文件。 不論該API所使用之授權及存取限制，均可採OAS標準進行描述。

API, Application Programming Interface, 應用程式介面

REST, Representational State Transfer, 含狀態傳輸 是一種軟體架構設計風格。

資源由 URI 指定，對資源的操作包括 取得、創建、修改、刪除，正好對應 HTTP 的協議 Get、POST、PUT、DELETE。

REST架構的限制

參考資料 : https://zh.wikipedia.org/wiki/%E8%A1%A8%E7%8E%B0%E5%B1%82%E7%8A%B6%E6%80%81%E8%BD%AC%E6%8D%A2

  • 客戶端-伺服器(Client-Server) 客戶端-伺服器結構限制的目的是將客戶端和伺服器端的關注點分離. 將使用者介面所關注的邏輯和資料儲存所關注的邏輯分離開來有助於提高使用者介面的跨平台的可移植性.通過簡化伺服器模組也有助於伺服器模組的可延伸性.

  • 無狀態（Stateless） 伺服器不能儲存客戶端的資訊, 每一次從客戶端傳送的請求中, 要包含所有的必須的狀態資訊, 對談資訊由客戶端儲存, 伺服器端根據這些狀態資訊來處理請求. 伺服器可以將對談狀態資訊傳遞給其他服務, 比如資料庫服務, 這樣可以保持一段時間的狀態資訊, 從而實現認證功能. 當客戶端可以切換到一個新狀態的時候傳送請求資訊. 當一個或者多個請求被傳送之後, 客戶端就處於一個狀態變遷過程中. 每一個應用的狀態描述可以被客戶端用來初始化下一次的狀態變遷.

  • 快取（Cacheability） 如同全球資訊網一樣, 客戶端和中間的通訊傳遞者可以將回覆快取起來. 回覆必須明確的或者間接的表明本身是否可以進行快取, 這可以預防客戶端在將來進行請求的時候得到陳舊的或者不恰當的資料. 管理良好的快取機制可以減少客戶端-伺服器之間的互動, 甚至完全避免客戶端-伺服器互動, 這進一步提了高效能和可延伸性。

  • 統一介面（Uniform Interface） 這是 RESTful 系統設計的基本出發點. 它簡化了系統架構, 減少了耦合性, 可以讓所有模組各自獨立的進行改進. 包括下列四個限制:

    • 請求中包含資源的 ID (Resource identification in requests) 請求中包含了各種獨立資源的標識, 例如, 在 Web 服務中的 URIs. 資源本身和傳送給客戶端的標識是獨立. 例如, 伺服器可以將自身的資料庫資訊以 HTML XML 或者 JSON 的方式傳送給客戶端, 但是這些可能都不是伺服器的內部記錄方式.

    • 資源通過標識來操作 (Resource manipulation through representations) 當客戶端擁有一個資源的標識, 包括附帶的元資料, 則它就有足夠的資訊來刪除這個資源.

    • 訊息的自我描述性 (Self-descriptive messages) 每一個訊息都包含足夠的資訊來描述如何來處理這個資訊. 例如, 媒體類型 (midia-type) 就可以確定需要什麼樣的剖析器來分析媒體資料.

    • 用超媒體驅動應用狀態 (Hypermedia as the engine of application state (HATEOAS)) 同用戶存取 Web 伺服器的 Home 頁面相似,當一個 REST 客戶端存取了最初的 REST 應用的 URI 之後, REST 客戶端應該可以使用伺服器端提供的連結,動態的發現所有的可用的資源和可執行的操作.隨著存取的進行, 伺服器在回應中提供文字超連結, 以便客戶端可以得到目前可用的操作. 客戶端無需用確定的編碼的方式記錄下伺服器端所提供的動態應用的結構資訊.

  • 分層系統（Layered System） 客戶端一般不知道是否直接連接到了最終的伺服器, 或者是路徑上的中間伺服器. 中間伺服器可以通過負載均衡和共享快取的機制提高系統的可延伸性,這樣可也便於安全策略的部署.

  • 按需代碼（Code-On-Demand，可選） 伺服器可以通過傳送可執行代碼給客戶端的方式臨時性的擴充功能或者客製化功能.例如Java Applet、Flash或JavaScript。

規範準則

共通性：採用 Open API Initiative 組織之 OpenAPI Specification 標準，作為 API 說明文件之一致標準。

輕便性：參考 現階段&未來趨勢 之 API 呼叫方式，採用 RESTful 風格 API。

標準化：參考國際通用 W3C 相關標準(如URI、HTTP等)及 OData.org 相關規範 訂定之。

範例

"/v2/Bus/RealTimeByFrequency/City/{City}":
{
    "get":
    {
        "tags":
        [
            "CityBusApi"
        ],
        "summary":"取得指定[縣市]的公車動態定時資料(A1)",
    }
}

Schema

在下列的描述中，如果某一個欄位沒有被標明 必要(REQUIRED)、必須(MUST)、應該(SHALL) 所描述的，都視為可選填。

  1. OpenAPI 物件 (OpenAPI Object)

    Field Name, Type, Description

    openapi: string, 必填 ， 載明該文件所使用的 OAS 版本。這個欄位 應該 要讓使用者可以用工具直譯其版本。這個欄位與API Info 版本號無關。

    info: Info Object, 必填 ， 提供這份 API 的詮釋資料。如有需要，這詮釋資料也可以由使用者使用。

    servers: [Server Object], 提供至目標伺服器的連結資訊。若未提供該欄位 or 空陣列，預設為跟目錄 "/"。

    paths: Path Object, 必填，記載這份API的功能操作及可用路徑。

    componets: Components Object, 用於記載保存於各種 schema 之元素。

    security: Security Requirement Object, 宣告其可跨用於整份API的安全機制。其清單內包含可供使用的 security requirement objects。 僅需有一項 security requirement objects 滿足授權需求即可。可藉由重複操作可以覆蓋此定義。

    tags: [Tag Object], 本標準於附加詮釋資料所使用的標籤清單。標籤順序可被分析工具所解析。並非所有 Operation Object 所使用的標籤都必須被宣告，未被宣告之標籤 可被隨機地或邏輯性組織起來。清單中每個標籤名稱都必得是獨一無二的。

    externalDocs:External Documentation Object, Additional external documentation。

  2. 資訊物件 (Info Object)

  3. 聯絡物件 (Contact Object)

  4. 授權物件 (License Object)

  5. 伺服器物件 (Server Object)

  6. 伺服器變數物件 (Server Variable Object)

  7. 元件物件 (Components Object)

  8. 路徑物件 (Paths Object)

  9. 路徑項目物件 (Path Item Object)

  10. 操作物件 (Operation Object)

  11. 外部文件物件 (Exxternal Documentation Object)

  12. 參數物件 (Parameter Object)

  13. Request Body 物件(Request Body Object)

  14. 媒體類型物件 (Media Type Object)

  15. 編碼物件 (Encoding Object)

  16. (複)回應物件 (Responses Object)

  17. 單一回應物件 (Response Object)

  18. 回呼物件 (Callback Object)

  19. 範例物件 (Example Object)

  20. 連結物件 (Link Object)

  21. 標頭物件 (Header Object)

  22. 標籤物件 (Tag Object)

  23. (複)範例物件 (Examples Object)

  24. 參考物件 (Reference Object)

  25. Schema 物件 (Schema Object)

  26. 識別物件 (Discriminator Object)

  27. XML 物件 (XML Object)

  28. 安全方案物件 (Security Scheme Object)

  29. OAuth 流程物件 (OAuth Flows Object)

  30. OAuth 單一流程物件 (OAuth Flow Object)

  31. 安全需求物件 (Security Requirement Object)

HTTP Status Code

參考資料:(https://tw.twincl.com/programming/*641y)

參考資料:(https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)

2xx: 成功

200 OK: 通用狀態碼 201 Created: 資源新增成功 202 Accepted: 請求已接受，但尚在處理中 204 No Content: 請求成功，但未回傳任何內容

3xx: 重新導向

301 Moved Permanently: 資源已移至它處 303 See Other: 回傳的內容可在它處取得（例如在用戶端發送了一個POST請求之後） 304 Not Modified: 請求的資源並未修改（通常是用戶端發送了帶有If-Modified-Since或If-None-Match表頭的請求）

4xx: 用戶端錯誤（用戶端不應retry原始請求）

400 Bad Request: 通用狀態碼 401 Unauthorized: 用戶端尚未驗證 403 Forbidden: 用戶端被禁止此請求 404 Not Found: 請求的資源不存在 405 Method Not Allowed: 不支援請求的HTTP方法 406 Not Acceptable: 不支援請求所要求的內容類型（Accept表頭） 415 Unsupported Media Type: 不支援請求所用的內容類型（Content-Type表頭）

5xx: 伺服器錯誤（用戶端可合理retry）

500 Internal Server Error: 工程師要找bug了 501 Not Implemented: 用戶端的請求目前未支援（也就是將來有可能支援） 502 Bad Gateway: 上游的伺服器未回傳正確結果，一般是gateway或proxy server才會回傳此狀態碼 503 Service Unavailable: 暫停服務（也就是過不久就會恢復服務──如果一切順利的話） 504 Gateway Timeout: 上游的伺服器逾時，一般是gateway或proxy server才會回傳此狀態碼

Previous利用DISC幫助溝通Next檔案上傳

Last updated