在開發領域這條路上，懵懵懂懂的走了3–5年，不是工程師，所以很多時候，知其然但不知其所以然，許多專有名詞、定義，對於非本科系出身的我，常常是不知道那個name、那個狀態該如何表達，然而在這段DevOps的日子，恍然大悟。

以下，透過API的藝術這堂課來呈見文件整理的部分。

Udemy上有一系列關於API的課程，作者是Peter Gruenbaum，是 SDK Bridge 的總裁。 SDK Bridge 是一家專門從事 API 文檔的公司。作者有感於好的開發人員都不擅長寫文件，甚至很不喜歡寫文件。即使開發人員寫得很好，但是他們太接近材料了。因此作者致力於為文檔帶來了重要的外部視角。使文件的建立對於同仁能夠更容易使用 API，提高採用率，不但解決問題，長遠看來更能夠降低公司成本，減緩技術債的積累。
這系列課程：
第1系列是關於結構化數據，什麼是JSON 和 XML以及如何記錄。
第2系列是關於常見的兩大Web API：REST 和 SOAP，以及如何記錄REST API。
第3系列是前2個的總和運用，引導思考並深入理解的內容，以及討論為什麼 API 文件如此重要，並討論概念材料和參考材料的區別。

以下筆記重點摘錄：
API（Application Programming Interface）解釋為 應用程式介面，扮演應用程式和應用程式之間的橋樑，定義了兩個軟件如何相互通信，所以有Web API（我們普遍意指的API）與平台API（如 Java、C++、Python 等編寫）的分別。在Web API中又分為Rest和SOAP最常見。

API文件分為兩個主要部分：概念部分和參考部分

在概念部分：

• 概述：為什麼使用 API、關鍵概念、工作流程和圖表。
• 說明：如何完成第一個任務。
• 用例：引導完成常見任務。
• 範例代碼：可以運行的code。

概念顯示架構和數據模型圖等可視化信息，引導開發人員並讓他們開始使用API。
參考文檔更加詳細，往往是包含信息的短句和表格。

API 可以做什麼？

首先為什麼要使用 API，描述關鍵功能並提供一些例子。
意指使用 API 構建的應用程序示例。例如，如果有一個在雲中存儲圖像的 API，那麼可以創建一個媒體資料庫的應用程序，公司可以將其數位影音媒體，將其價值數據存儲在雲中。

對於每個概念，寫一兩段解釋它是什麼以及它如何工作。例如，對於學習管理系統，關鍵概念可能是角色（即教師、學生、管理員等）、班級、成績等。銀行系統可能具有賬戶、交易等概念。
在架構部分描述了高層發生的事情。需要解釋 API 的主要部分，然後解釋所有這些部分如何組合在一起。工作流程則描述了這些先後調用的順序。

API種類

• Web API，涵蓋 Web 請求Request和回應Response。包括註冊、獲取應用程序密鑰、授權以及執行發出一兩個HTTP請求以返迴響應。盡量避免需要復雜授權的任務。例如：任何需要OAuth 的事情。
• 平台 API，說明該API支持哪些編程語言，以及需要哪些操作系統、下載 SDK、設置 IDE整合開發環境，甚至內容的版本號和創建簡單的應用程序等。

小結

這個課程內容，除了建立API文件的重要性和結構、方法之外，還介紹了**＂Stripe＂**這家使用API而歷久不衰再創高峰的公司。以及其他Tools 幫助處理API，圖形用戶界面工具（GUI）和命令行工具（cURL），工具對於嘗試 REST 請求非常有用。 通過使用工具 發出請求，將更好地了解 REST API 工作原理。例如：Postman 或 Swagger。

這段時光最大的收穫則是看懂系統架構與文件的意義，在自學進修的路上有跡可循。