微信截圖_17259503964071.png)
使用 REST，以下 GET 示例可用于從產(chǎn)品列表中返回特定資源：
http://dzone.com/products/2此 URI 將返回 ID 等于 2 的產(chǎn)品：
{
"id": 2,
"name": "Product Two"
}在客戶端表示資源時(shí)，如果調(diào)用者具有適當(dāng)?shù)臋?quán)限，則可以進(jìn)行修改和刪除。使用上面的示例，可以構(gòu)造以下 JSON 數(shù)據(jù)：
{
"id": 2,
"name": "Product Two Updated"
}并作為 PUT 請(qǐng)求的正文傳遞給以下 URI：
http://dzone.com/products/2如果 PUT 請(qǐng)求成功，則 ID=2 的產(chǎn)品名稱將從“Product Two”更改為“Product Two Updated”。
作為 REST 消息的一部分，指定了 Internet 媒體類型（以前稱為 MIME 類型），以便可以調(diào)用正確的解析器。常見的 Internet 媒體類型是“application/json”。
RESTful 客戶端在訪問(wèn) URI 路徑時(shí)，能夠發(fā)現(xiàn)所需的所有可用操作和資源，從而避免了信息硬編碼的需要。
RESTful 服務(wù)契約可以分為以下四個(gè)區(qū)域：
RESTful 應(yīng)用程序依賴于 API 生態(tài)系統(tǒng)的底層安全性，而不是在 REST 架構(gòu)樣式中直接包含安全性。除了使用 HTTPS 協(xié)議保護(hù) RESTful API 調(diào)用外，還應(yīng)使用基于會(huì)話的身份驗(yàn)證。目前，大多數(shù) RESTful 應(yīng)用程序都利用 OAuth 2.0 和 OpenID Connect（OIDC）協(xié)議。
RESTful API 建模語(yǔ)言（RAML）是一種用于描述 RESTful API 的語(yǔ)言。RAML 使用 YAML 這種人類可讀的數(shù)據(jù)序列化語(yǔ)言編寫。自 2013 年首次提出以來(lái)，RAML 得到了 MuleSoft、AngularJS、Intuit、Box、PayPal、可編程 Web 和 API Web Science、Kin Lane、SOA Software 和 Cisco 等技術(shù)領(lǐng)導(dǎo)者的支持。RAML 的目標(biāo)是提供描述 RESTful API 所需的所有信息，從而簡(jiǎn)化 API 設(shè)計(jì)過(guò)程。
以下是一個(gè)由 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 提供了一個(gè)完整的 API 設(shè)計(jì)生命周期，分為五個(gè)階段：
通過(guò)使用易于閱讀的 YAML 格式，API 設(shè)計(jì)變得更加直觀。利用專用的 RAML 工具（如 API Workbench 和 API Designer）或 IDE 插件（如 Sublime 和 Visual Studio），可以加快開發(fā)速度，減少代碼重復(fù)，并對(duì) API 進(jìn)行原型設(shè)計(jì)和完善。在 RAML 文件中構(gòu)建 API 構(gòu)建塊后，可以添加模擬數(shù)據(jù)，以便在編寫實(shí)際代碼之前進(jìn)行原型設(shè)計(jì)和測(cè)試，從而在開發(fā)早期驗(yàn)證 API。
設(shè)計(jì)完成后，可以開始對(duì) API 邏輯進(jìn)行實(shí)際編程。此時(shí)，RAML 文件成為規(guī)范，流行語(yǔ)言如 NodeJS、Java、.NET、Mule 和 IOT Noble 等可以簡(jiǎn)化構(gòu)建過(guò)程。以下是一個(gè)基于 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 規(guī)范提供了另一種選擇。
在設(shè)計(jì)和建模階段之后，API 開發(fā)生命周期的下一個(gè)邏輯步驟是測(cè)試。這些單元測(cè)試對(duì)于確保 API 保持向后兼容性，并滿足當(dāng)前要求至關(guān)重要。Abao、Vigia 和 Postman 等工具允許導(dǎo)入 RAML 規(guī)范，創(chuàng)建設(shè)置腳本和測(cè)試以驗(yàn)證 API。此外，測(cè)試服務(wù)如 API Fortress、API Science 和 SmartBear 提供了對(duì)延遲、響應(yīng)、有效載荷和錯(cuò)誤的測(cè)試支持。
API 文檔通常是一個(gè)挑戰(zhàn)，工具如 Swagger 和 Miredot 可能無(wú)法提供完整的信息，導(dǎo)致依賴開發(fā)人員指定注釋和 JavaDocs 等特定于語(yǔ)言的文檔。由于 RAML 規(guī)范將文檔作為核心優(yōu)先事項(xiàng)，文檔與代碼保持同步。RAML 規(guī)范充當(dāng) API 的接口（或合同），與底層業(yè)務(wù)邏輯同步。API 控制臺(tái)、RAML 轉(zhuǎn) HTML 和 PHP RAML2HTML 等工具提供了快速簡(jiǎn)便的方式來(lái)公開標(biāo)準(zhǔn)化文檔，這些文檔可以在公司內(nèi)部網(wǎng)上保密或供公眾使用。
在 API 開發(fā)生命周期中的所有構(gòu)建塊都已就位后，最后一個(gè)階段是共享 API。RAML 規(guī)范引入了幾種集成 API 的方法：
SDK 生成：使用 RAML 文件可以自動(dòng)構(gòu)建 Java、.NET、PHP、Ruby、NodeJS、iOS、Windows 和 Go 等語(yǔ)言的軟件開發(fā)套件（SDK）。
第三方工具：Oracle 和 MuleSoft 將 RAML 功能包含在他們的工具集中，只需粘貼規(guī)范即可連接到任何使用 RAML 的 API。
API Notebook：為開發(fā)人員提供一個(gè)環(huán)境，用于測(cè)試 API、操作 API 調(diào)用的結(jié)果，并使用 JavaScript 語(yǔ)言連接到多個(gè) API。
JAX-RS 和 RAML 的關(guān)聯(lián)關(guān)系在于它們共同支持 RESTful API 的開發(fā)生命周期。RAML 專注于 API 的設(shè)計(jì)和描述，而 JAX-RS 專注于 API 的實(shí)現(xiàn)。在實(shí)踐中，開發(fā)者可以先使用 RAML 定義 API 的結(jié)構(gòu)和行為，然后利用 JAX-RS 實(shí)現(xiàn)這些定義。這種結(jié)合使用可以提高開發(fā)效率，確保 API 的一致性和可維護(hù)性。
RAML 規(guī)范 0.8 仍然是當(dāng)前標(biāo)準(zhǔn)，但版本 1.0 自 2016 年 9 月開始獲得支持。版本 1.0 包括以下更新：
對(duì) RESTful API 進(jìn)行版本控制一直是一個(gè)爭(zhēng)論不休的話題，主要圍繞版本控制的實(shí)施方式。版本控制的三個(gè)主要選項(xiàng)是 URI、HTTP 標(biāo)頭和消息架構(gòu)標(biāo)識(shí)符。
雖然沒有正確或錯(cuò)誤的答案，但建議設(shè)定一個(gè)標(biāo)準(zhǔn)并堅(jiān)持執(zhí)行，以減少 API 消費(fèi)者的混淆。
基于 URI 的版本控制方法在 RESTful API 的 URI 中包含版本號(hào)。例如，產(chǎn)品 API 的 3.0 版本如下所示：
http://dzone.com/v3.0/products這種方法最為流行，因?yàn)榭梢郧宄乜吹秸谑褂玫?API 版本。然而，批評(píng)者認(rèn)為，資源的 URI 不應(yīng)僅因?yàn)?API 版本變化而更改。
HTTP 標(biāo)頭方法旨在保持 URI 的干凈，并在標(biāo)頭中添加版本信息。產(chǎn)品 API 的 3.0 版本將使用以下通用 URI：
http://dzone.com/products但 HTTP 標(biāo)頭將包含以下信息：
HTTP GET:
https://dzone.com/products
api-version: 3.0雖然 URI 始終相同，但批評(píng)者認(rèn)為這種方法不描述資源的語(yǔ)義。
與 HTTP 標(biāo)頭選項(xiàng)類似，消息架構(gòu)標(biāo)識(shí)符（或內(nèi)容類型）版本控制策略在標(biāo)頭中創(chuàng)建自定義 Internet 內(nèi)容類型。使用相同的通用 URI：
http://dzone.com/products標(biāo)頭已更新為反映自定義內(nèi)容類型：
Accept: application/vnd.dzone.app.products-v3.0+json雖然 URI 始終相同，但批評(píng)者指出版本引用被隱藏，自定義的 Internet 內(nèi)容類型可能復(fù)雜且難以測(cè)試。
雖然對(duì)公共 API 來(lái)說(shuō)這不是一個(gè)選項(xiàng)，但在內(nèi)部開發(fā) API 并對(duì)所有使用者有影響和控制權(quán)的情況下，可能會(huì)考慮不實(shí)施版本控制。這種做法可以避免版本控制和維護(hù)多個(gè)版本的挑戰(zhàn)。
批評(píng)者認(rèn)為，這種方法只是避開了需要解決的版本控制問(wèn)題。因此，即使是私有 API，也應(yīng)設(shè)計(jì)為公開可用的資源，并包括版本控制的需求。
API 生命周期的管理包括以下核心方面，每個(gè)方面都有其特定的步驟和任務(wù)：
微信截圖_17259504408995.png)
設(shè)計(jì)生命周期與 RAML 開發(fā)生命周期相似，重點(diǎn)是 API 的初步構(gòu)思和設(shè)計(jì)過(guò)程，包括：
微信截圖_17259504568475.png)
實(shí)施階段專注于實(shí)際的程序開發(fā)和測(cè)試，包括：
微信截圖_17259504759419.png)
管理階段處理 API 的運(yùn)營(yíng)、維護(hù)和優(yōu)化，包括：
微信截圖_17259504939867.png)
/api/v1/resource，這樣可以在不影響舊版本客戶端的情況下對(duì)API進(jìn)行更新。RESTful API 生命周期管理包括三個(gè)核心方面：設(shè)計(jì)、實(shí)現(xiàn)和管理。這三個(gè)方面涵蓋了 API 的整個(gè)生命周期，從概念到驗(yàn)證，再到實(shí)施和最終棄用。生命周期建立在經(jīng)過(guò)驗(yàn)證的 RESTful API 設(shè)計(jì)之上，并將簡(jiǎn)單性包裹在這些概念周圍，以確保穩(wěn)定、安全的實(shí)現(xiàn)，并能夠根據(jù)需要進(jìn)行擴(kuò)展。
RAML 的引入有助于在設(shè)計(jì)階段標(biāo)準(zhǔn)化元素，使得組織能夠更好地構(gòu)建、交付和記錄 API。其架構(gòu)適應(yīng)了整個(gè) RESTful API 生命周期管理結(jié)構(gòu)，并使用標(biāo)準(zhǔn)命名法提供了清晰的指導(dǎo)。
原文鏈接：RESTful API Lifecycle Management