Python 實時聊天室搭建：發布訂閱頻道API實戰應用
使用 REST，以下 GET 示例可用于從產品列表中返回特定資源：
http://dzone.com/products/2此 URI 將返回 ID 等于 2 的產品：
{
"id": 2,
"name": "Product Two"
}在客戶端表示資源時，如果調用者具有適當的權限，則可以進行修改和刪除。使用上面的示例，可以構造以下 JSON 數據：
{
"id": 2,
"name": "Product Two Updated"
}并作為 PUT 請求的正文傳遞給以下 URI：
http://dzone.com/products/2如果 PUT 請求成功，則 ID=2 的產品名稱將從“Product Two”更改為“Product Two Updated”。
作為 REST 消息的一部分，指定了 Internet 媒體類型（以前稱為 MIME 類型），以便可以調用正確的解析器。常見的 Internet 媒體類型是“application/json”。
RESTful 客戶端在訪問 URI 路徑時，能夠發現所需的所有可用操作和資源，從而避免了信息硬編碼的需要。
RESTful 服務契約可以分為以下四個區域：
RESTful 應用程序依賴于 API 生態系統的底層安全性，而不是在 REST 架構樣式中直接包含安全性。除了使用 HTTPS 協議保護 RESTful API 調用外，還應使用基于會話的身份驗證。目前，大多數 RESTful 應用程序都利用 OAuth 2.0 和 OpenID Connect（OIDC）協議。
RESTful API 建模語言（RAML）是一種用于描述 RESTful API 的語言。RAML 使用 YAML 這種人類可讀的數據序列化語言編寫。自 2013 年首次提出以來，RAML 得到了 MuleSoft、AngularJS、Intuit、Box、PayPal、可編程 Web 和 API Web Science、Kin Lane、SOA Software 和 Cisco 等技術領導者的支持。RAML 的目標是提供描述 RESTful API 所需的所有信息，從而簡化 API 設計過程。
以下是一個由 MuleSoft 提供的 Notes 示例 API 的 RAML 文件示例：
#%RAML 0.8
title: Notes Example API
version: v2
mediaType: application/json
documentation:
- title: Overview
content: This is an example of a simple API for a "notes" service
/notes:
description: A collection of notes
get:
description: List all notes, optionally filtered by a query string
queryParameters:
q:
description: An optional search query to filter the results
example: shopping
responses:
200:
body:
example: |
[ { "id": 1, "title": "Buy some milk", "status": "done" },
{ "id": 2, "title": "Return sweater", "status": "overdue", "dueInDays": -2 },
{ "id": 3, "title": "Renew license", "status": "not done", "dueInDays": 1 },
{ "id": 4, "title": "Join gym", "status": "not done", "dueInDays": 3 } ]
post:
description: Create a new note in the collection
body:
example: |
{ "title": "Return sweater", "dueInDays": -2 }
headers:
X-Tracking-Example:
description: You can specify request headers like this
enum: [ accounting, payroll, finance ]
required: false
example: accounting
responses:
201:
headers:
X-Powered-By:
description: You can describe response headers like this
example: RAML
body:
example: |
{
"id": 2,
"title": "Return sweater",
"status": "overdue",
"dueInDays": -2
}
/{id}:
description: A specific note, identified by its id
uriParameters:
id:
description: The id of the specific note
type: number
example: 2
get:
description: Retrieve the specified note
responses:
200:
body:
example: |
{
"id": 2,
"title": "Return sweater",
"status": "overdue",
"dueInDays": -2
}RAML 提供了一個完整的 API 設計生命周期，分為五個階段：
通過使用易于閱讀的 YAML 格式，API 設計變得更加直觀。利用專用的 RAML 工具（如 API Workbench 和 API Designer）或 IDE 插件（如 Sublime 和 Visual Studio），可以加快開發速度，減少代碼重復，并對 API 進行原型設計和完善。在 RAML 文件中構建 API 構建塊后，可以添加模擬數據，以便在編寫實際代碼之前進行原型設計和測試，從而在開發早期驗證 API。
設計完成后，可以開始對 API 邏輯進行實際編程。此時，RAML 文件成為規范，流行語言如 NodeJS、Java、.NET、Mule 和 IOT Noble 等可以簡化構建過程。以下是一個基于 Java 和 JAX-RS 框架的 RAML 示例：
@Path("/notes")
public interface NotesExampleResource
{
@POST
@Consumes("application/json")
Response createNote(Note note, @Context UriInfo uriInfo);
@GET
@Produces("application/json")
Notes getNotes(@QueryParam("q") String query);
}使用 RAML for JAX-RS 框架，Java 接口也可以生成 RAML 文件，這為利用 RAML 規范提供了另一種選擇。
在設計和建模階段之后，API 開發生命周期的下一個邏輯步驟是測試。這些單元測試對于確保 API 保持向后兼容性，并滿足當前要求至關重要。Abao、Vigia 和 Postman 等工具允許導入 RAML 規范，創建設置腳本和測試以驗證 API。此外，測試服務如 API Fortress、API Science 和 SmartBear 提供了對延遲、響應、有效載荷和錯誤的測試支持。
API 文檔通常是一個挑戰，工具如 Swagger 和 Miredot 可能無法提供完整的信息，導致依賴開發人員指定注釋和 JavaDocs 等特定于語言的文檔。由于 RAML 規范將文檔作為核心優先事項，文檔與代碼保持同步。RAML 規范充當 API 的接口（或合同），與底層業務邏輯同步。API 控制臺、RAML 轉 HTML 和 PHP RAML2HTML 等工具提供了快速簡便的方式來公開標準化文檔，這些文檔可以在公司內部網上保密或供公眾使用。
在 API 開發生命周期中的所有構建塊都已就位后，最后一個階段是共享 API。RAML 規范引入了幾種集成 API 的方法：
SDK 生成：使用 RAML 文件可以自動構建 Java、.NET、PHP、Ruby、NodeJS、iOS、Windows 和 Go 等語言的軟件開發套件（SDK）。
第三方工具：Oracle 和 MuleSoft 將 RAML 功能包含在他們的工具集中，只需粘貼規范即可連接到任何使用 RAML 的 API。
API Notebook：為開發人員提供一個環境，用于測試 API、操作 API 調用的結果，并使用 JavaScript 語言連接到多個 API。
JAX-RS 和 RAML 的關聯關系在于它們共同支持 RESTful API 的開發生命周期。RAML 專注于 API 的設計和描述，而 JAX-RS 專注于 API 的實現。在實踐中，開發者可以先使用 RAML 定義 API 的結構和行為，然后利用 JAX-RS 實現這些定義。這種結合使用可以提高開發效率，確保 API 的一致性和可維護性。
RAML 規范 0.8 仍然是當前標準，但版本 1.0 自 2016 年 9 月開始獲得支持。版本 1.0 包括以下更新：
對 RESTful API 進行版本控制一直是一個爭論不休的話題，主要圍繞版本控制的實施方式。版本控制的三個主要選項是 URI、HTTP 標頭和消息架構標識符。
雖然沒有正確或錯誤的答案，但建議設定一個標準并堅持執行，以減少 API 消費者的混淆。
基于 URI 的版本控制方法在 RESTful API 的 URI 中包含版本號。例如，產品 API 的 3.0 版本如下所示：
http://dzone.com/v3.0/products這種方法最為流行，因為可以清楚地看到正在使用的 API 版本。然而，批評者認為，資源的 URI 不應僅因為 API 版本變化而更改。
HTTP 標頭方法旨在保持 URI 的干凈，并在標頭中添加版本信息。產品 API 的 3.0 版本將使用以下通用 URI：
http://dzone.com/products但 HTTP 標頭將包含以下信息：
HTTP GET:
https://dzone.com/products
api-version: 3.0雖然 URI 始終相同，但批評者認為這種方法不描述資源的語義。
與 HTTP 標頭選項類似，消息架構標識符（或內容類型）版本控制策略在標頭中創建自定義 Internet 內容類型。使用相同的通用 URI：
http://dzone.com/products標頭已更新為反映自定義內容類型：
Accept: application/vnd.dzone.app.products-v3.0+json雖然 URI 始終相同，但批評者指出版本引用被隱藏，自定義的 Internet 內容類型可能復雜且難以測試。
雖然對公共 API 來說這不是一個選項，但在內部開發 API 并對所有使用者有影響和控制權的情況下，可能會考慮不實施版本控制。這種做法可以避免版本控制和維護多個版本的挑戰。
批評者認為，這種方法只是避開了需要解決的版本控制問題。因此，即使是私有 API，也應設計為公開可用的資源，并包括版本控制的需求。
API 生命周期的管理包括以下核心方面，每個方面都有其特定的步驟和任務：
設計生命周期與 RAML 開發生命周期相似，重點是 API 的初步構思和設計過程，包括：
實施階段專注于實際的程序開發和測試，包括：
管理階段處理 API 的運營、維護和優化，包括：
/api/v1/resource，這樣可以在不影響舊版本客戶端的情況下對API進行更新。RESTful API 生命周期管理包括三個核心方面：設計、實現和管理。這三個方面涵蓋了 API 的整個生命周期，從概念到驗證，再到實施和最終棄用。生命周期建立在經過驗證的 RESTful API 設計之上，并將簡單性包裹在這些概念周圍，以確保穩定、安全的實現，并能夠根據需要進行擴展。
RAML 的引入有助于在設計階段標準化元素，使得組織能夠更好地構建、交付和記錄 API。其架構適應了整個 RESTful API 生命周期管理結構，并使用標準命名法提供了清晰的指導。
原文鏈接：RESTful API Lifecycle Management
