API入门指南： Software Engineering中理解和使用API的初学者指南

你有沒有想过你如何能夠登入你最喜欢的應用程式，比如Facebook、Hashnode、dev.to、LinkedIn等等？我知道我引起了你的注意，你開始快速思考。或者你有没有想过如何才能輕鬆地登入WakaNow航班應用程式，並獲得來自全世界最便宜、最实惠的票價？甚至足球愛好者也不落後，因為他們可以实时接入比分。

這些問題的答案就是他們通過API与其他系統進行通信以獲取這些數據，或者驗證詳細信息。

在本文中，將解開API的概念，並學習到非常清晰、恰當的API是什麼、它們的類型以及它們的操作方式。

API，即應用程序接口，是一個讓系統或技術通過分享信息或數據自我溝通的工具。進一步來說，它可以解釋為一個層次，讓系統之間根據一定的協議或標準進行分享。

API重要是因为它讓系統和技術能夠彼此互動、分享數據和功能，並共同創造強大、高效的系統。此外，API還授予開發者將應用程序集合起來的超能力以執行特定任務。例如，一個時尚博客可以整合 Flutterwave API 讓顧客为学生支付设计或研讨会费用，你也可以使用你的Google账户登录到与之关联的任何应用程序。

API可以從第三方獲取數據和交流信息，使我們作為軟件工程師能夠做到瘋狂的事情。

讓我們來進行一個類比，你想要在大學學習。你必须遵循一系列過程，這將包括參加考試以及根據成績申請你希望的機構。你不需要直接去找入學辦公室進行申請，而是只需要訪問他們的網站，輸入你的詳細信息並上傳证明文件。在等待入學的過程中，後端会发生一系列你不知道的事情，但如果滿足要求，你將收到入學通知。

整個過程如下，我們想要與學校入學辦公室溝通，由於我们不能直接訪問入學辦公室，因此我們使用一個API層，在這個場景中是學校網站，你將稱之為 端點。每個端點都有其必要的協議和预期的結果。在這個例子中，學校網站讓你免於處理入學辦公室的複雜問題。

假設沒有申請门户網站，您將需要前往大學招生辦公室提交您的資料，這將浪費時間，也不免於錯誤。

要通過互聯網將兩個軟件應用程序連接起來，一個稱為客戶端的程序會向另一個應用程序的API發送請求。客戶端會從應用程序的数据庫中請求資源，或者要求服務器執行某個動作。

在接收到並驗證客戶端的請求後，API會執行所需的動作並將回應返回給客戶端。這個回答包括請求的状态（已完成或拒絕）以及客戶端請求的任何資源。

圖1. API的運作

大约有四种不同的API，將進行解釋。

一些公有API的例子包括；Bitquery、Adoptapet、covalenthq。

私人 API 或內部 API 是一種只供開發者或建造它的人使用的 API。只有當擁有者向第三方發送邀請時，才能進行訪問。

一些私人 API 的例子包括；

  1. Twilio 的程式化語音 API

  2. Stripe 的連接 API

  3. Google 地圖的企業私人 API

  4. Salesforce 的 Metadata API

  5. GitHub Enterprise API

由企業或組織提供給外部開發者或夥伴，使其能夠與其服務、數據或平台進行溝通和互動的應用程序開發接口（API）稱為合作伙伴 API，也稱為第三方 API 或開發者 API。這些 API 旨在讓系統、程式或服務的整合變得更加容易。

希望扩大其產品或服務用途並促進與外部開發者或企業合作的組織經常提供合作伙伴 API。在這些 API 的幫助下，夥伴可以創造程序、工具或服務，利用企業的數據、功能或技術。

一些合作伙伴 API 的例子包括：

  1. Twitter 合作伙伴 API

  2. Spotify 開發者 API

  3. Dropbox 合作夥伴 API

  4. eBay 開發者計劃 API

  5. Amazon 產品廣告 API

复合 API，又稱為聚合 API 或撷取 API，是一種將多個底层 API 或服務的資訊或功能混合與集中的 API。這些 API 通過讓開發者透過一個 API 存取並互動於不同的服務，簡化整合過程並提供多個數據來源的綜合視覺。

當程式設計師需要從多個來源不斷地接收信息或執行多個動作時，复合 API 是有幫助的。复合 API 讓開發者能夠發送一個請求來訪問數據或横跨多個服務執行動作，而不是發送分開的請求到每個 API。透過這種方式，整合過程得到優化，複雜性減少，而且效率提高。

以下是一個聚合多個天氣服務提供商數據的复合 API 示例：

  1. WeatherAPI

  2. OpenWeatherMap API

  3. Weatherbit API

為了聚合這些供應商的數據並為開發者提供一个單一的天氣數據接口，可以創建一個复合 API。這讓開發者能夠只通過一個 API 請求，從多個來源獲取天氣信息。

网際網路上最常见的API莫過於Web API，因為我們的大部分日常生活都與網際網路上進行。Web API是一套標準，讓不同瀏覽器上的事物能夠保持一致。這是指溝通的雙方面。Web API，通常稱為應用程序介面（API），是由网路服務或應用程序提供的介面，使線上溝通和互動成為可能。開發人员可以通過Web API以程式化方式訪問网路應用程序或服務的某些功能、服務或數據。

1. RESTful API

RESTful API指的是代表性状态转移應用程序介面，是一套標準，讓電腦能夠遵循REST（代表性状态转移）建築設計原則，在網際網路上進行溝通。

REST API的组成部分包括

  1. 请求 —–→ 响应

  2. 操作 – GET, POST, PATCH, UPDATE, DELETE

  3. 端点 – 网址

  4. 参数/体

  5. 头文件

图2 REST API示意图

REST的關鍵原則包括：

  1. 客戶-服務器架構：REST將客戶端和服務器部件分開，使其能夠獨立演化。客戶端將請求發送到服務器，服務器處理這些請求並回傳响应。

  2. 無狀態性：REST是无状态的，這意味著客戶端發送到服務器的每個請求都必須包含理解與處理請求所必需的所有信息。服務器在請求之間不儲存任何客戶端上下文，簡化了可伸縮性並允許更好的缓存。

  3. 統一接口：REST促進了一種统一的接口和操作，通常使用標準的HTTP方法如GET、POST、PUT和DELETE。RESTful系統中的每個資源都 uniquely identified by a URL (Uniform Resource Locator)。

  4. 資源为基础: REST將一切視為資源，例如數據實體、服務或收集。每個資源都有唯一的标识，可以使用標準的HTTP方法來訪問和操作。

  5. 資源表示: REST中的資源使用特定格式表示，如JSON（JavaScript物件表示法）或XML（可擴展標記語言）。服務器將資源表示傳送回客戶端，可以包括數據、元數據或超媒體链接。

  6. 無狀態交互相 interaction: 客戶端發送至服務器的每個請求都是自包含的，並且不依賴於服務器上的任何先前請求或狀態。這有助於更好的可擴展性，因為服務器不需要維護客戶端會话信息。

REST API的好處

  1. 簡單且標準化

  2. 可擴展且無狀態

  3. 高性能且可缓存

2. SOAP API

SOAP（Simple Object Access Protocol）是指簡單物件存取協定，是遵循SOAP Web服務規格的Web服務。它是一種使用XML作為格式、有其確定之模式以及用戶標準的協定，由万維网聯盟定義。SOAP協定覆蓋了廣泛的互聯網通讯協定，特別是HTTP、SMTP及TCP/IP。

圖 3 SOAP API 示意圖

使用 SOAP API 的益處

  1. 語言、平台和傳輸是中立的。

  2. 在分布式企業環境中表現良好。

  3. 透過 WS* 標準提供顯著的前建的擴展性。

  4. 內建錯誤處理。

  1. RPC。

遠程程序 calls (RPC) 協定是一個傳送多個參數並接收結果的手段。它是一個遠程函數調用，它不存在於您的本地電腦上，但需要從調用它的位置部署。它在一定程度上是異步的，因為您需要獲得一個回應以標記為成功。它是客戶端和服務器之間的直接交互相遇。RPC API 引起操作或過程的執行。RPC 可以採用兩種不同的語言，JavaScript 物件字串格式 (JSON) 和 XML。

圖 4 一個 RPC 協定

  1. GraphQL API

GraphQL 是一個用於 API 的查询语言，允許客戶端请求特定的数据，并根据他们的需求塑造回应。

一些 GraphQL API 的例子

GitHub GraphQL API, Shopify GraphQL API, SpaceX GraphQL API, Yelp GraphQL API, Twitter GraphQL API (Twitter API v2).

比較 API 協定

REST

SOAP

RPC

GraphQL

支援 XML、JSON、HTTP 和文字格式

設計上支援 XML

要求使用者知道程序名稱

支援 HTTP

與數據合作良好

與流程（动作）合作良好

特定的參數和順序

安全性溫和

安全性進階

文件可以通過超媒體補充

開發者使用起來最困難

需要廣泛的文件

请求方法有 GET、PUT、DELETE、PATCH、UPDATE。

请求方法是 POST

请求方法是 POST

请求方法是 POST

A. 端點

API 端點是溝通渠道的一端或端點。當 API 与另一個系統互動時，這種溝通的接触點稱為端點。字面上來說，APIs 傳送資源的地方以及資源离开的地方稱為端點。在 APIs 中，端點通常是 uniform resource locator (URL)，提供服務器上資源的位置。

端點的例子有

Twitter API 端點示例

Twitter API 揭露關於推文、直接消息、用戶等數據。

比方說你想要取回特定推文的内容。為了這個目的，你可以使用 推文查找端點，其 URL 為 api.twitter.com/2/tweets{id}（其中 {id} 是推文的唯一標識符）。

B. 請求和响應

API 請求是從客戶端發送給服務器的消息。API 請求是對 API 发出以訪問或修改數據或執行特定動作的要求。API 響應是對 API 請求返回的數據或信息。

例如，用戶點擊下方的超連結；

<a href=’http://localhost:2400/categories/01/flavours ’>

顯示口味類別中所有可用的口味

</a>

它們將以 HTTP 請求消息的形式發送：

GET /categories/01/flavours HTTP/1.1

主機: localhost:2400

用戶代理: Chrome/5.0 [兼容, Windows 10]

API 請求

1. Copy codeGET https://api.com/categories/flavours

API 回應

1. Copy codeHTTP/1.1 200 OK

2. Content-Type: application/json

3.

4. {

5. "id": 01,

6. "flavours": "Chocolate"

7. }

從這個請求中可以看到，端點是 URL – /categories/01/flavours。

請求方法是 GET，HTTP 規格是 1.1，域是 localhost，端口是 2400，Flavours 是資源，用戶代理提供了瀏覽器和操作系統信息。

C. HTTP 方法 (GET, POST, PUT, DELETE)

使用 HTTP 協議的 API 利用 HTTP 請求方法 (也稱為 “HTTP 動詞”) 傳送客戶端的請求到服務器。最常用的 HTTP 請求方法有 GET、POST、PUT 和 DELETE。

  1. GET 用於客戶端從服務器索取數據，

  2. PUT 取代既有數據或如果不存在則創建數據，

  3. POST 主要用於創建新資源，

  4. PATCH 用以部分更新來自資源的數據，並且

  5. DELETE 移除客戶端在服務器上指定的數據或資源。

D. API 安全 – 身份驗證和授權

這兩個詞語雖然聽起來類似，但各有不同的功能。身份驗證與用戶身份的核实有關，而授權則與用戶具有的訪問權限或被授予的操作許可有關。它們是 API 安全的核心，一種流行的用戶身份驗證和授權方法是 OAuth 2.0。

授權的不同類型

授權有几种方法。以下是一些您可能會遇到的 API 授權類型：

E. API 金鑰和憑證

API 金鑰是一串文字，用於提供客戶端應用程式的識別和授權。换个说法，它們用於識別對伺服器進行調用的應用程式，以及該調用應用程式是否已被授予存取 API 伺服器的權限。它用於追蹤所有活動並阻擋任何恶意行為。

API 金鑰驗證是为了解決共享登入信息的不完善，這是 HTTP 基本驗證的重大問題。它可能用於兩個目的。第一步是識別正在向您後端 API 調用の客戶端應用程式。第二步是客戶端應用程式授权，決定調用應用程式是否已被授予調用 API 的權限。

API 金鑰是從在网路上应用程序管理的 API 金鑰提供者那裡得到的。

在哪里存放您的 API 金鑰

永远不要將您的金鑰嵌入代码中或文件中，因為當您推送到 GitHub 时，它們可能会公之於众，而是將您的 API 金鑰存放在環境變量中。

API 金鑰的一个例子可能是以下形式。

key: a9nIbdnaoks97028Jlf.ains9NIKQMEO

存取令牌是一種安全性憑證，用於驗證和授權存取 API（應用程式程式介面）。令牌只是持有者的唯一憑證，該持有者被允許存取 API。

以下是 JSON Web 令牌（JWT）的示例：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

此令牌由三個部分組成，用點分隔：頭結點、负载和簽名。頭結點通常包含有关令牌签名的算法信息，例如：

{

"alg": "HS256",

"typ": "JWT"

}

负载包含關於实体（用戶、客戶端等）的声明或陈述，並可以包括如为主体、發行者、过期時間和自訂數據等信息。例如：

{

"sub": "1234567890",

"name": "John Doe",

"iat": 1516239022

}

簽名是通過取 encoded 頭結點、负载和一個秘密金鑰，並應用如 HMAC-SHA256 的加密算法來創建的。簽名確保了令牌的完整性與真实性。

當使用此 JWT 时，客戶端將它包含在 API 請求的授權頭結點中，如下所示：

授權：Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

API服務器可以进而驗證令牌的真實性、檢查其過期時間，並使用令牌 payload 中的信息進行授權等用途。

請注意，這裡提供的示例令牌僅為說明用途，不應在生產環境中使用。

令牌和金鑰都用於驗證和授權，但它們在以下方面有所不同：

API 金鑰通常用於訪問 API 时的客戶端或應用程序識別和驗證。它們通常呈現為長串隨機生成的字符串，作為凭证。另一方面，令牌在成功識別後授予受授權的客戶端或用戶，作為識別驗證的證據。

令牌有效期：除非 API 提供者故意吊銷或更換，API 金鑰通常具有長久有效期。另一方面，令牌通常具有短有效期和過期日期。根據識別技術，客戶端必须在令牌过期後重新識別或使用刷新令牌以獲得新令牌。

安全：相比API金鑰，令牌通常提供更出色的安全功能。令牌可以設計成具有有限的範圍或權限，允許精細的訪問控制。它們也可以被加密、签名的，或包含額外的声明，提供完整性和真实性。這使得身份驗證更安全，並更好地保護敏感數據。

A. 天氣API

天氣API，或應用程序編程接口，是提供实时访问天氣數據和预报的服务。

例子包括

。 WeatherAPI.com, Forecast, Meteostat。

B. 社交媒體API

社交网络API允许这些平台与其他软件供应商和应用程序整合。

例子包括

C. 付款闸道 API

允許軟件開發者將付款闸道服務 incorporation 到他們的應用程序或網站中的技術接口被稱為付款闸道 API。

例如

Stripe API。Stripe 是一個广受好评的服務，允許銷售商在線接受付款，Noodlio Pay，Square API，PayPal，Adyen，Paybook，KeyPay，BIPS 發票 (由 Coinify 提供)。

D. 地圖和地理位址 API

地理位址 API 不會保留任何資訊，而是允許您從被查询的設備收取现有數據。它可能會從不同的來源收集位置數據，包括 IP 位址、GPS、WiFi、藍牙、RFID、GSM/CDMA ID 以及人工輸入。

包括 地理定位 API, Mapbox API, OpenStreetMap API, MapQuest API, HERE API。

肆. 結論 暨 學習重点

本文中，已經论述了 API 的是什麼、如何工作、實際生活中的例子、APISecurity、HTTP 方法以及 API 的重要性。推断 API 讓軟件工程師能夠將應用程序整合到正在建设中，甚至能夠進行優化。在進行研究與寫作過程中，我發現 API 安全是一個非常大的問題。如果 API 被黑的話，將會影響所有與它連接的應用程序，因此我將進一步研究 API 安全。

最後，我將發表另一篇相關文章，因為這將是關於探索 API、在代碼中使用 API、API 最佳實踐、API 設計和開發。

A. 一些關鍵詞包括

API – 應用程序用戶接口

RPC – 遠程程序呼叫

HTTP – 超文本傳輸協議

B. 進一步學習的下一步

終於，我將发布另一篇文章，因為它將涉及探索API、在代碼中使用API、API最佳實踐、API設計和開發。

Source:
https://nechey.hashnode.dev/introduction-to-apis-a-beginners-guide-to-understanding-and-utilising-apis-in-software-engineering