REST API 設計與生成：使用 Visual Paradigm 的綜合指南 - Go TOGAF Traditional Chinese

引言

在現代軟體開發世界中，應用程式介面（API）已成為不同系統與服務之間數位通訊的骨幹。在各種 API 設計架構風格中，REST（具象狀態傳輸）因其簡潔性、可擴展性與無狀態特性，已成為主導方法。REST API 使不同的軟體應用程式能夠透過標準 HTTP 協定在網路上進行通訊，使其具備平台無關性且廣泛可存取。

然而，設計、文件化與實作 REST API 可能是一個複雜且耗時的過程，特別是在確保一致性、適當的文件以及服務提供者與消費者皆能輕鬆使用時。這正是 Visual Paradigm 發揮作用的時刻——一款強大的建模工具，能簡化從設計到部署的整個 REST API 生命週期。

模型驅動 REST API 開發

本綜合案例研究探討 Visual Paradigm 如何促進完整的 REST API 開發流程，涵蓋從使用 UML 類別圖進行初始設計，到生成可投入生產的程式碼與完整的 API 文件。我們將從提供者（設計與實作 API）與消費者（存取與使用 API）的雙重視角，逐步說明整個流程，並提供各階段的實務見解。

理解 REST API 基礎

什麼是 REST API？

REST 這個詞代表具象狀態傳輸。它是一種用於設計網路應用程式的架構風格。符合 REST 架構約束的 Web 服務 API 被稱為 RESTful，或 REST API。

REST API 運作於資源之上，這些資源由統一資源識別碼（URI）進行識別。這些資源透過標準的 HTTP 方法進行操作，例如 GET、POST、PUT、PATCH 與 DELETE。REST 的關鍵原則包括：

無狀態性：每個來自客戶端的請求都包含處理該請求所需的所有資訊
客戶端與伺服器分離：客戶端與伺服器獨立運作
快取性：回應必須明確標示是否可快取
統一介面：用於操作資源的標準方法

Visual Paradigm 如何支援 REST API

Visual Paradigm 支援對 REST API 的底層通訊模型進行建模，以及生成 REST API 與 API 文件。該平台提供視覺化方法來設計 RESTful 服務，使概念化、文件化與實作 API 變得更加容易。

以下活動圖表顯示提供者為產生 REST API 與相關 API 文件將採取的步驟：

活動圖 - 提供者如何設計並生產 REST API？

活動圖表——提供者如何設計並產生 REST API？

首先，服務提供者將使用類別圖設計通訊模型，以視覺化呈現 REST 服務、請求與回應主體。接著，他可從該類別圖生成 REST API 與 API 文件。之後，提供者可繼續編寫服務邏輯程式碼。完成後，他即可部署服務並將 API 發布至其網站。

以下活動圖表顯示消費者為使用該服務將採取的步驟：

活動圖 - 客戶如何透過 REST API 存取服務？

活動圖表——客戶端如何透過 REST API 存取服務？

服務消費者可瀏覽 API 文件頁面，下載 XML 檔案，然後將該 XML 檔案匯入 Visual Paradigm。如此一來，他們即可生成存取該服務所需的原始碼與 API。最後一步則是使用所生成的原始碼編寫使用該服務的應用程式。

第一部分：使用 UML 設計 REST API

如何使用 UML 設計 REST API？

您可以透過繪製代表資源、請求與回應主體的類別圖來設計您的 REST API。

繪製 REST 資源

REST 資源是符合 REST 規範的 Web 服務的基本單位。它是一個具有 URI、HTTP 請求方法、相關參數以及請求/回應主體的对象。每個 REST 資源代表一個在由其 URI 屬性指定的路徑上可用的特定服務。因此，如果您要建模多個服務，請繪製多個 REST 資源。

繪製 REST 資源的逐步指南

步驟 1：建立新的類別圖

選取圖形 > 新增從應用程式工具列。在「新增圖形」視窗中，選取類別圖，然後按一下下一步。輸入圖形名稱與描述，然後按一下確定.

步驟 2：選取 REST 資源工具

選取REST 資源於圖形工具列中。

在圖表工具列中選擇 REST 資源

在圖形工具列中選取 REST 資源

步驟 3：建立 REST 資源

按一下圖形以建立 REST 資源。為資源命名時，請使用簡短且有意義的名稱。

已建立 REST 資源

REST 資源已建立

步驟 4：開啟資源規格

在 REST 資源上按右鍵，然後選取開啟規格…於快顯功能表。

開啟 REST 資源的規格

正在開啟 REST 資源的規格

步驟 5：填寫一般屬性

在「一般索引標籤，填入以下內容：

屬性	說明
URI	每個 REST 資源都有其專屬的 URI。消費者透過 URL 存取 REST 資源。通常，RESTful URI 應指向一個實體資源，而非指向某個動作。因此，在決定 URI 時，請盡量使用名詞而非動詞。
方法	指定要對資源執行的動作。詳細資訊，請參閱以下章節：方法（HTTP 方法）。
說明	將出現在所產生 API 文件中的資源說明。建議提供清晰的服務說明，讓消費者了解該服務為何以及如何使用它。

REST 資源的一般屬性

已填入 URI、方法與描述

已填入 URI、方法與說明

步驟 6：建立請求主體模型（適用於 POST、PUT、PATCH、DELETE）

若 REST 資源使用 POST、PUT、PATCH 或 DELETE 方法，且在執行該資源時需要參數，請透過繪製類別來建立參數模型。將滑鼠游標移至 REST 請求主體 圖示。按下 資源目錄 按鈕並將其拖曳出來。

從 REST 請求主體建立類別

從 REST 請求主體建立類別

放開滑鼠按鈕，並選擇 關聯 -> 單一類別 從資源目錄。

選擇單一類別

選擇單一類別

放開滑鼠按鈕以建立請求類別。預設情況下，類別名稱會根據 REST 資源命名。您可以自行重新命名。例如，若您要透過 /members REST 資源建立會員，您可能需要將會員詳細資料傳送給伺服器以建立會員記錄。因此，將類別命名為會員以儲存會員詳細資料。

已從 REST 請求主體建立類別

從 REST 請求主體建立的類別

將屬性加入類別中。這些屬性將儲存傳送給伺服器的資料。

已新增屬性

已新增屬性

以下是類別模型與 JSON 格式請求體表示之間的比較。

類別模型與 JSON 格式請求主體之間的比較

類別模型與 JSON 格式請求體的比較

步驟 7：建立回應體模型

現在，您可以繼續設計 REST 資源的回應部分。將滑鼠指標移至「REST 回應體圖示。如果服務將傳回簡單的資料值或物件，請按「資源目錄按鈕並將其拖曳出來。接著，選擇「關聯 → 單一類別從資源目錄。如果服務將傳回物件陣列，請選擇「關聯 → 多類別從資源目錄。

從 REST 回應主體建立類別

從 REST 回應體建立類別

為類別命名並將屬性新增至該類別。

已從 REST 回應主體建立類別

已從 REST 回應體建立類別

以下是類別模型與 JSON 格式回應體表示之間的比較。

類別模型與 JSON 格式回應主體之間的比較

類別模型與 JSON 格式回應體的比較

為使用 GET 方法的 REST 資源指定參數

參數指的是用於將資料傳遞至服務的查詢參數。例如，當您使用「貨幣轉換」服務時，您可能需要將要轉換的金額、目前幣別與目標幣別傳遞至服務，以換取轉換後的金額。因此，要轉換的金額、目前幣別與目標幣別即為該服務的參數。

參數的特性之一是它們是可選的。參數的另一個特性是它們不具唯一性，這表示您可以多次新增相同的參數。

提交 HTTP 請求時，參數會附加至 URL 的路徑。帶有參數的 URL 可能如下所示：「http://www.example.com?age-limit=18

要將參數新增至 REST 資源：

在 REST 資源上按右鍵，然後選擇「新增參數從快顯選單。

新增參數

新增參數

輸入參數的名稱。如有需要，您也可以指定類型。請注意，類型的指定僅供文件記錄之用。雖然它有助於使用者了解預期資料的類型，但在程式碼層級不會產生任何影響。在程式設計中，參數一律放入以字串作為鍵與值的 Map 中。

已建立參數

已建立參數

按「輸入.
重複步驟 2 和 3 以建立所有參數。按Esc 在完成建立所有參數後。

已建立參數

參數已建立

模擬多種情境

有時您可能需要模擬多種情境，其中可能包含多個或多種不同的回應主體。例如，您希望定義可回傳的各種 HTTP 狀態碼，且在某些情況下，您可能需要在主要回應物件中嵌入錯誤物件。

範例：

案例 1：

回應標頭：status : 200 OK
回應主體：{“customer” : {“name” : “Peter”}}

案例 2：

回應標頭：status : 400 Bad Request
回應主體：{“customer”: {“error” : {“text” : “無效的客戶名稱。”}}}

要表示此情況，只需從 REST 資源拖曳多個回應主體。當拖曳第二個回應主體時，系統將提示您輸入狀態碼。您也可以透過右鍵點擊連接 REST 資源與回應主體的關聯，並選擇 狀態碼… 從彈出式選單中。

正在建立第二個回應主體

建立第二個回應主體

第二部分：指定標頭與範例

指定請求標頭與請求範例

HTTP 訊息由 HTTP 請求行、一組標頭欄位以及可選的訊息主體組成。為了讓消費者能夠存取 REST 資源，您必須指定請求標頭與請求（主體）範例。如此一來，請求標頭與範例將顯示在產生的 API 文件中。消費者即可依據該規範來使用服務。

右鍵點擊 REST 資源並選擇 開啟規格… 從彈出式選單中。
開啟 請求主體 索引標籤。
輸入標頭正如我們在 REST API 概覽頁面中所說，REST 並非標準，而是一種架構風格。REST 利用 HTTP 標準，因此，任何 REST 呼叫的標頭實際上都是 HTTP 標頭。
輸入「範例」（以 JSON 格式）。

已指定請求標頭與範例

已指定請求標頭與範例

指定回應標頭與回應範例

同樣地，您需要指定回應標頭與回應（主體）範例。如此一來，回應標頭與範例將顯示在生成的 API 文件檔中。

在 REST 資源上按右鍵，然後選擇「開啟規格…」從彈出式選單中。
開啟「回應主體」 索引標籤。
輸入「標頭」.
輸入「範例」（以 JSON 格式）。

已指定回應標頭與範例

已指定回應標頭與範例

標頭（HTTP 標頭）

HTTP 標頭是任何 HTTP 請求與回應的核心組成部分，並定義了任何 HTTP 交易的運作參數。當您在網頁瀏覽器中造訪某個 URL 時，您的瀏覽器會發送 HTTP 請求，其內容可能如下所示：

GET / HTTP/1.1
Host: www.visual-paradigm.com
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:33.0) Gecko/20100101 Firefox/33.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Cookie: landing=b7b93a316f374b13af4d5904c9797dcc; __utma=...
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

正如我們先前所說，REST 並非標準，而是一種架構風格。REST 利用 HTTP 標準。因此，任何 REST 呼叫的標頭實際上都是 HTTP 標頭。

方法（HTTP 方法）

HTTP 方法（有時也稱為 HTTP 動詞）指定了對資源執行的動作。最常用的 HTTP 方法包括 GET、PUT、POST 和 DELETE，分別對應讀取、更新、建立與刪除操作。

方法	說明
GET	GET 方法（或 GET 請求）用於取得資源的表示形式。它應僅用於取得資料，且不應造成任何變更。
PUT	PUT 方法（或 PUT 請求）用於更新資源。例如，如果您知道某篇部落格文章位於 http://www.example.com/blogs/123，您可以使用 PUT 方法將該文章的新資源表示形式置入，以更新該特定文章。
POST	POST 方法（或 POST 請求）用於建立資源。例如，當您想要新增一篇部落格文章，但不知道要儲存在何處時，您可以使用 POST 方法將文章發布至某個 URL，並由伺服器決定該 URL。
PATCH	PATCH 方法（或 PATCH 請求）用於修改資源。它包含對資源的變更內容，而非完整的資源。
DELETE	DELETE 方法（或 DELETE 請求）用於刪除由 URI 識別的資源。

不同 HTTP 方法的說明

第三部分：從 UML 產生 REST API

完成 REST 資源的建模後，您可以產生 API，並可選擇性地產生 API 文件。

產生 REST API（提供者觀點）

要產生 REST API：

選取工具 > 程式碼 > 產生 REST API…從工具列。
在REST API視窗中，保持提供者選取為API 類型。如此，您將能夠產生 API 文件，以及伺服器範例程式碼，該程式碼將指導您編寫服務（邏輯）的程式。

選擇要產生的 REST 資源

選取要產生的 REST 資源

選取要產生程式碼的 REST 資源。
產生器將使用儲存在範本目錄進行程式碼產生。您可以編輯範本，或選取其他目錄作為範本目錄。
勾選產生 API 文件以產生顯示如何使用所選 REST 資源的 HTML 檔案。預期您將把產生的 API 文件發布到您的網站，以便您的服務使用者可以閱讀它，了解如何存取您的服務。
輸入您的公司名稱，該名稱將顯示在 API 文件中。
輸入您服務的基礎 URL。
勾選 產生範例以產生教導您如何程式化您服務的原始碼。範例程式碼內容豐富且具資訊性。因此，我們強烈建議您不要從頭開始程式化，而是產生範例程式碼並修改其內容以符合您的需求。
輸入程式碼的輸出路徑。

已輸入輸出路徑

已輸入輸出路徑

按產生。根據勾選/取消勾選的選項，您可能會在輸出目錄中看到以下資料夾：

資料夾	說明
doc	API 文件。您應將 API 文件發布到您的網站，以便您的服務使用者可以查看文件以學習 API。
lib	為了讓產生的程式碼正常運作，Google Gson 函式庫必須出現在您的類別路徑中。請手動從 https://code.google.com/p/google-gson/ 下載該函式庫，並將檔案放置於 lib 資料夾中。
sample_src	客戶端與 Servlet 的範例程式碼。它向您展示如何作為客戶端進行存取，以及如何作為提供者回應請求。我們強烈建議您複製該程式碼，並填入您自己的服務邏輯以進行修改。
src	通訊模型的原始碼。請勿修改檔案內容，否則程式碼可能無法正常運作。

產生檔案說明

第 4 部分：如何使用產生的 REST API？

RESTful 服務的使用者必須經過一系列步驟，以取得存取 REST 資源所需的 API 程式碼。

使用者逐步指南

步驟 1：瀏覽 API 文件

瀏覽服務提供者發布的服務 API 文件。API 文件應如下所示：

REST API 文件

REST API 文件

步驟 2：下載 REST API 模型 XML

您可以透過閱讀 API 文件來學習 REST 資源的用法。若要取得 API 程式碼，請將 API 文件向下捲動至底部。點擊頁面底部的 REST API 模型 XML 檔案下載連結。

下載 REST API 模型 XML

下載 REST API 模型 XML

步驟 3：下載並安裝 Visual Paradigm

從官方網站下載 Visual Paradigm。安裝並執行它。

步驟 4：匯入 XML 檔案

在 Visual Paradigm 中匯入 REST API 模型 XML 檔案，請選擇專案 > 匯入 > XML…從工具列中選擇。

步驟 5：指定匯入設定

在匯入 XML視窗中，輸入 XML 檔案的路徑，然後按匯入.

匯入 XML 視窗

匯入 XML 視窗

步驟 6：開啟類別圖

在圖表索引標籤中的專案瀏覽器，雙擊由匯入 XML 檔案所建立的類別圖。

開啟類別圖表

開啟類別圖

步驟 7：檢視通訊模型

您現在可以看到 REST 資源的通訊模型，其外觀如下：

通訊模型

通訊模型

步驟 8：產生 API 程式碼

選擇工具 > 程式碼 > 產生 REST API…從工具列中選擇。

步驟 9：選擇消費者作為 API 類型

在REST API 視窗，選擇 消費者 作為 API 類型.

選擇消費者作為 API 類型

選擇消費者作為 API 類型

步驟 10：選擇 REST 資源並設定產生

選擇要產生程式碼的 REST 資源。

選擇要產生的 REST 資源

選擇要產生的 REST 資源

跳過公司欄位，因為您在程式設計中其實不需要它。輸入服務的基礎 URL。勾選 產生範例 以產生教導您如何存取服務的原始程式碼。輸入程式碼的輸出路徑。

已輸入輸出路徑

已輸入輸出路徑

步驟 11：產生並使用程式碼

按一下產生。根據選項的勾選/取消勾選狀態，您可能會在輸出目錄中看到以下資料夾：

資料夾	說明
lib	為了讓產生的程式碼能正常運作，您的類別路徑中必須包含 Google Gson 函式庫。請從 https://code.google.com/p/google-gson/ 手動下載該函式庫，並將檔案放置於 lib 資料夾中。
sample_src	此範例程式碼展示如何存取服務。我們強烈建議您複製該程式碼，並填入您自己的應用程式邏輯進行修改。
src	通訊模型的原始程式碼。請勿修改檔案內容，否則程式碼可能無法正常運作。

產生檔案說明

結論

Visual Paradigm 提供了一套全面且高效的解決方案，用於設計、記錄和生成 REST API。透過利用 UML 類別圖，開發人員可以視覺化地建立其 API 資源、請求/回應主體以及各種情境的模型，確保在整個開發過程中保持清晰與一致性。

使用 Visual Paradigm 進行 REST API 開發的主要優勢

視覺化設計: 利用 UML 圖表以視覺化方式設計 REST API，使流程更加直觀且易於上手，降低團隊成員與利害關係人的學習門檻。
一致性: 透過從單一真實來源（UML 模型）生成程式碼與文件，Visual Paradigm 確保設計、實作與文件之間的一致性。
文件生成: 自動生成完整的 API 文件可節省大量時間，並確保文件與實際實作保持同步。
程式碼生成: 為提供者與消費者生成範例程式碼可加速開發，並降低在實作 API 通訊模型時產生錯誤的風險。
雙向工作流程: 匯出與匯入 XML 模型的能力促進了服務提供者與消費者之間的無縫協作，確保雙方對 API 的理解一致。
多情境支援: 能夠以不同狀態碼建立多個回應情境的模型，使 API 設計更為全面，涵蓋各種使用情境與錯誤條件。

使用 Visual Paradigm 進行 REST API 設計的最佳實踐

URI 使用名詞: 設計 URI 時，應使用名詞來表示資源，而非使用動詞來表示動作。
定義清晰的描述: 為您的資源、參數與範例提供清晰的描述，以確保使用者能理解如何操作您的 API。
建立所有情境的模型: 包含成功與錯誤回應情境，以完整呈現您 API 的行為。
提供範例: 務必提供請求與回應範例，以說明預期的有效負載結構。
生成並審查文件: 務必生成並審查 API 文件，以確保其準確反映您的設計。
使用範例程式碼: 將生成的範例程式碼作為實作的起點，而非從零開始。

未來考量

隨著軟體開發環境持續演變，支援視覺化建模與程式碼生成的工具（如 Visual Paradigm）將變得越來越重要。它們使團隊能夠：

維持一致性跨越大型團隊與複雜系統
縮短開發時間透過自動化
提升品質透過消除手動翻譯錯誤
增強協作在不同利害關係人之間

透過採用 Visual Paradigm 進行 REST API 的設計與生成，組織可以簡化其 API 開發流程，交付更高品質的 API，並為 API 消費者提供更佳的體驗。

參考資料

REST API 概覽: REST API 概念概覽及 Visual Paradigm 對 REST API 生成的支援
使用 UML 建模 REST API: 在 Visual Paradigm 中使用 UML 類別圖設計 REST API 的詳細指南
如何使用 UML 設計 REST API: 使用 UML 圖表設計 REST API 的實用步驟
如何從 UML 生成 REST API: 從 UML 模型生成 REST API 程式碼的逐步說明
如何使用生成的 REST API: 針對消費者使用所生成 REST API 程式碼的指南
Visual Paradigm 教學: 開始使用 Visual Paradigm 的教學彙編
Visual Paradigm YouTube 頻道: 影片資源與示範
Visual Paradigm 專業知識: 包含技巧、秘訣與解決方案的知識庫
Visual Paradigm 支援: 支援與聯絡資訊