API和RESTful API是每個程式設計師都應該熟悉的基本概念。在設計 API 時，應滿足一些基本要求，以確保系統之間有效率且有效的互動。

如果您仍然不熟悉API是什麼或尚未掌握 RESTful API 的概念，請花 5 分鐘繼續閱讀。我將以簡單易懂的方式解釋一切。

❓ 什麼是 API？

• 一個簡單的例子可以清楚地說明這一點：

• 早在2000年，網路購票就開始興起，但大多數人還是靠打電話查詢航班。最初，您會致電當地車站詢問可用的航班或火車時刻表。收到訊息後，您可以前往相應的車站購買車票。

• 隨著科技的快速進步和智慧型手機的廣泛使用，各種旅遊App不斷湧現，教大家如何透過這些App購買門票。

• 現在，買票變得更加簡單。透過在應用程式中輸入您的出發地和目的地，您可以查看所有相關的火車和航班選項。您不僅可以獲得有關時間和座位可用性的訊息，還可以獲得有關航空公司、預計持續時間等的詳細訊息，並以清晰簡潔的方式呈現。您可以根據您的具體需求輕鬆購買。

• 連結是一件美妙的事。在我們現在的生活中，我們可以透過各種App毫不費力地購物、閱讀、體驗直播，以前所未有的方式與世界和人們聯繫。

• 那麼這一切怎麼可能呢？是什麼讓應用程式如此方便？訊息如何從A點傳送到B點，讓我們只要動動手指就能完成一切？

• API 是實現這一切的橋樑——網路世界的無名英雄。 API的完整形式是應用程式介面。簡單來說，它是由品牌開發的介面，使第三方能夠建立額外的功能並將其整合到自己的產品中。

• 回到之前提供的範例：

• 過去，如果我們想了解航班訊息，就需要一個信使。電話上的操作員充當了這個信使，或者我們所說的 API。他們將您的請求傳達給系統。例如，如果您要求第二天飛往紐約的航班，接線員會檢索資訊並將其轉發給您。

• 現在，當我們需要購買機票時，我們只需與預訂系統互動即可選擇日期、城市和艙位偏好。該系統從各個航空公司網站收集資料，並透過與航空公司互動的 API 來聚合這些資訊。

• 我們現在了解到，正是 API 使我們能夠使用這些旅行應用程式，而這項原則普遍適用於生活各個方面的應用程式、資料和設備之間的互動。這些系統中的每一個都使用自己的 API 來相互建立連接。

❓ 什麼是 RESTful API？

• 在網路的早期，當它還沒有完全成為主流並且行動裝置還沒有那麼普及時，對 API 的需求相對較低。當時，Web應用程式主要在伺服器端執行，由於頁面請求量和並髮用戶量有限，使用複雜的協定進行資料操作和傳輸。

• 隨著行動裝置的使用激增，從這些裝置存取 Web 應用程式的必要性變得至關重要。這種轉變標誌著使用者行為和期望的重大變化，需要客戶端和伺服器之間採用更有效的通訊方式。在這裡，API 的作用變得至關重要，因為它們充當了允許行動裝置與 Web 應用程式無縫互動的橋樑。

• 因此，一套簡化開發、結構清晰、標準化、易於理解和可擴展的API對於廣泛接受和可用性變得越來越重要。 RESTful API風格完美地體現了這些特徵，導致其逐漸在開發者和組織中出現和流行。

休息

• REST，代表Representational State Transfer，是一種設計風格和軟體架構風格，而不是一個嚴格的標準。它提供了一組指導網頁應用程式建立的設計原則和限制。 REST 的目標是利用 Web 的特性（特別是 HTTP 協定）來建立可擴充且有效率的服務。

寧靜的

• RESTful 這個詞只是作為形容詞來描述遵循 REST 原則的 API 或服務。例如，RESTful API 是一種說明 REST 概述的特徵和設計限制的 API。它確保 API 模仿 REST 架構，提供可預測且標準化的互動模式。

RESTful API

• 我們平常會遇到的常見API是這樣的：

• 然而，RESTful API 看起來像這樣：

💡六大原則

• Roy Fielding是 HTTP 協定的主要架構師之一。在他的論文中，他詳細闡述了 REST 架構的概念，並概述了其六個約束，通常稱為六大原則。這些原則可作為建立 RESTful API 的指南，並有助於其功能和可擴充性。讓我們仔細看看每個原則：

統一介面

• 就像我們之前觀察到的兩個插圖一樣，API 最直觀的特徵是它遵循 REST 架構的原則。統一的介面對於 RESTful 服務至關重要。客戶端只需專注於介面的實現，增強了API的可讀性，方便使用者存取。

• RESTful API 透過 URL 定位資源並透過 HTTP 方法操作這些資源。資源的操作包括取得、建立、更新和刪除，直接對應HTTP協定的GET、POST、PUT和DELETE。

• GET：檢索資源資訊。

• POST：建立新資源。

• PUT：更新現有資源。

• 刪除：刪除現有資源。

• 在完全遵循 RESTful 原則的團隊中，後端只需要告知前端有關 /users API 的訊息，而前端應該本質上理解以下操作：

• 取得所有使用者： GET /users

• 檢索特定使用者： GET /users/{id}

• 建立一個新使用者： POST /users

• 更新現有使用者： PUT /users/{id}

• 刪除使用者： DELETE /users/{id}

• 隨著API數量的成長和系統變得越來越複雜，RESTful架構的優勢變得更加明顯。透過專注於一系列資源可以簡化對系統的理解，這有助於理解和記憶保留。

客戶端-伺服器

• 這意味著客戶端和伺服器是獨立的，可以相互解耦。

• 客戶端負責請求和處理資料，伺服器負責儲存資料和處理請求。

• 這兩個元件透過一組約定進行協作，以確保客戶端可以有效地取得所需的資料。

無國籍狀態

• 這是指每個請求都是獨立的，與先前的請求沒有關係的原則。伺服器不維護有關客戶端的任何狀態訊息，每個請求都必須包含處理它所需的所有資訊。

• 這種方法的好處是它簡化了每個請求，使其易於理解和處理，並且更容易擴展和維護。

• 例如，考慮您登入網站的場景。您在登入介面輸入使用者名稱和密碼，並透過API取得令牌。從那時起，所有後續請求都必須攜帶此令牌，而不是系統在第一次成功登入後追蹤您的登入狀態。

可緩存性

• 客戶端和伺服器可以協商可快取的內容，允許伺服器透過設定適當的 HTTP 狀態碼來通知客戶端是否可以快取特定資料。

• 例如，HTTP 回應可能包含 Cache-Control 標頭，該標頭向用戶端傳達資料可以快取多長時間。這提高了資料傳輸的效率，減少了網路頻寬的使用，並加快了資料存取速度。透過有效管理快取內容，應用程式可以為用戶提供更快的回應時間和更無縫的體驗。

分層系統

• 客戶端不應該擔心請求經過了多少中間層；他們的主要關注點應該是請求的結果。一個設計良好的架構可以分為多個層，每個層獨立負責完成其特定的任務。這種分層方法使系統更易於維護，並允許獨立替換或增強各個層。

• 例如，資料庫儲存層可以獨立於架構中的其他層運作。這種獨立性使開發人員能夠替換或擴展資料庫層，而不會影響其他層的操作。這種模組化不僅簡化了開發流程，還增強了系統的整體彈性和可擴展性。

按需編碼

• 客戶端不應該關心請求經過了多少中間層；他們只需要專注於請求的結果。

• 系統的架構可以分成多層，每一層負責完成自己的任務。這種分層結構使系統更易於維護，並允許不同層的獨立更換。

• 例如，資料儲存層可以獨立於其他層進行操作。這意味著它可以被替換或擴展，而不會影響其他層的功能。這種模組化促進了應用程式架構內更好的可維護性和可擴展性。

🔥 RESTful API 設計指南

• 在討論 RESTful API 的理論方面後，是時候將我們的注意力轉向實踐方面了：如何設計最簡單的 RESTful 風格 API？

HTTP 方法

• HTTP 設計了各種動詞來表示不同的動作，每種 HTTP 請求方法都有自己的意義。如上所述，RESTful API 應使用 HTTP 方法（例如 GET、POST、PUT 和 DELETE）來描述對資源的運作。

版本控制

• 版本控制是指在不影響現有客戶端應用程式的情況下更新 RESTful API。常見的版本控制方法包括：

• URL方式：透過改變URL來表示不同的版本，例如https://api.example.com/api/v1/resources和https://api.example.com/api/v2/resources。

• Accept 標頭：使用請求標頭中的 Accept 欄位來指示所需的 API 版本。

• 請求參數：透過請求參數指定版本，例如https://api.example.com/resources?version=1、https://api.example.com/resources?version=2。

• 不同的公司和團隊可能會採用不同的 API 設計方法，但我相信保持版本控制方法盡可能簡單和直覺至關重要。將版本直接放在URL中，簡單明了，更方便開發者理解使用。

URL 清楚標識資源

• API應該使用簡潔、清晰的URL來辨識資源，同時使用不同的HTTP方法對相同資源執行各種操作。

• 這種設計使客戶能夠找到所需的資源，而無需額外的資訊或大量文件。清晰的 URL 為客戶端提供了與 API 有效互動的簡單方法。

• 相較之下，不規則 URL 可以有多種形式，需要不同的開發人員深入研究文件以了解如何與其互動。非結構化 URL 可能會導致開發混亂和效率低下。

• 在 URL 中遵循標準化的 RESTful 風格會產生固定格式，從而增強可讀性。透過依賴清晰的名詞和對應的HTTP動詞，開發人員可以輕鬆地對資源進行操作，從而在使用API時獲得更直觀的體驗。

• 這裡有一個小提示：如果您發現自己很難找到合適的 URL，您可以參考GitHub Open API 。它具有豐富的結構良好、組織有序的 URL 設計。

HTTP 狀態碼

• HTTP狀態程式碼是RESTful API設計的重要組成部分，用於指示API請求的狀態並通知客戶端請求是否成功以及資料是否已正確處理。一些常用的HTTP狀態碼包括：

• 200 OK ：請求成功，請求的資料已取得。

• 201 Created ：請求成功，建立了新資源。

• 204 No Content ：請求成功，但沒有資料返回，表示操作完成。

• 400 Bad Request ：由於格式不正確或缺少所需參數，請求失敗。

• 401 Unauthorized ：由於身分驗證問題或缺乏授權，請求失敗。

• 403 Forbidden ：請求失敗，因為客戶端沒有存取資源的權限。

• 404 Not Found ：請求失敗，因為請求的資源不存在。

• 500 內部伺服器錯誤：由於內部伺服器錯誤，請求失敗。

• 這些狀態程式碼可幫助客戶了解其請求的結果，並允許開發人員有效地處理錯誤和成功場景。

統一回傳資料格式

• RESTful APIs常用的回傳資料格式包括JSON和XML 。

• JSON （JavaScript 物件表示法）由於其簡單、輕量級且易於解析而成為目前流行的資料格式。它的可讀性使其在伺服器和客戶端之間資料交換頻繁的 Web 應用程式中特別受到青睞。

• XML （可擴展標記語言）是另一種廣泛使用的資料格式。它的優勢在於其靈活性和對各種資料類型的支援。 XML 可以表示複雜的資料結構，有時在需要文件驗證或更具描述性的格式的場景中是首選。

結構良好、美觀的 API 文件

• 在任何專案開發中，尤其是實現前後端分離時，API都起著至關重要的作用。因此，對 API 的依賴自然會延伸到維護更新且全面的 API 文件的重要性。然而，許多程式設計師發現建立文件很乏味，我甚至遇到過使用Word文件精心製作公司API文件的情況。

• 幸運的是，市場上有許多專門用於管理和記錄 API 的工具。每個開發人員或團隊可能都有自己的偏好，但我想推薦一個出色的 API 管理工具，稱為 Apidog。該工具讓您只需點擊幾下即可產生 API 文件。

• Apidog最好的部分是它顯著簡化了文件流程。您無需執行大量操作，只需透過使用者友好的視覺化介面新增 API，該工具就會自動為您產生文件。

🌟 最後的想法

• 總而言之，雖然RESTful風格的 API 確實有效且結構良好，但許多網路公司在設計 API 時並沒有嚴格遵守其準則。這是因為REST更像是一種風格，而不是一套不靈活的規則；過於理想化的RESTful APIs實作可能會導致巨大的成本和複雜性。

• 如果您正在考慮使用RESTful APIs ，請確保它們符合您的業務需求。例如，如果您的專案需要複雜的資料交互，您可能需要探索更好地滿足這些要求的替代 API 設計方法。

• 因此，在選擇 API 設計方法時，充分考慮您的業務需求至關重要。此外，請確保RESTful API與您的系統架構和技術堆疊相容。這些考慮因素將有助於確保RESTful APIs的正確利用，最終帶來更有效率、更可靠的 API 效能。

• 從長遠來看，API 設計不應被視為僅是後端團隊的責任；它應該是產品設計過程中整個產品團隊之間協調的協作努力。全面的方法可確保考慮到 API 使用的所有方面（從可用性到功能）。

• 對 API 和RESTful APIs的簡要概述強調，雖然不強制嚴格執行這些標準，但擁有RESTful指南等參考資料是非常寶貴的。此類指南可以提供重要的見解和最佳實踐，從而顯著提高 API 的設計和效率。希望這些資訊對每個人的 API 開發和實施之旅都有幫助。

📖 參考文獻

[1]GitHub開放API：https://docs.github.com/en/rest/actions/artifacts

[2]Apidog：https://apidog.com/

原文出處：https://dev.to/geekvergil/stop-building-messy-apis-heres-your-clean-code-guide-4h95