以下是我們在上面代碼中聲明的Root屬性的描述：
最佳做法是在Root級別定義標題、版本、baseUri、mediaType 和協議。RESTful API 建模語言文件名采用小寫的字母數字字符，使用 kebab 大小寫（即連字符分隔）。
這是您需要定義 API 資源的重要步驟之一，資源以 （/） 開頭。使用這些資源，您可以控制使用者或客戶端如何使用 API。
括在大括號中的資源是一個 uri 參數。URI 參數（Path Param）基本上用于標識一個或多個特定資源。
作為最佳實踐，資源名稱必須始終是復數形式，并且它應該是名詞而不是動詞。
/accounts:
/{accountId}:
/balances:
/transactions:
/{transactionId}:REST API 支持多種 HTTP 方法，如下所示：
我們可以為每個資源定義方法，并且每個資源可以有多個 http 方法。
API 應該只為資源提供名詞，并讓 HTTP 動詞（GET、POST、PUT、DELETE）定義要對資源執行的操作。使用 POST、DELETE 或 PUT 而不是 GET 來更改狀態。不要使用 GET 更改更改。
/accounts:
get:
post:
/{accountId}:
get:
/balances:
get:
/transactions:
get:
/{transactionId}:
get:我們已經根據用例為我們的資源定義了適當的方法。
Query 參數基本上用于對資源進行過濾或排序。它以鍵值形式作為查詢字符串在 URL 中傳遞。
在我們的用例中，我們需要獲取交易，并且可以根據日期范圍對其進行過濾。我們將使用 fromDate 和 toDate 作為查詢參數來篩選交易。
使用 URL 中定義的查詢參數從服務器篩選資源。
/accounts:
get:
headers:
customerId:
required: true
type: string
example: "323232"
maxLength: 20
post:
/{accountId}:
get:
/balances:
get:
/transactions:
get:
/{transactionId}:
get:
queryParameters:
fromTransactionDate:
type: date-only
example: "2021-08-01"
required: false
toTransactionDate:
type: date-only
example: "2021-08-20"
required: false我們需要獲取特定客戶的所有帳戶。在本例中，我們將使用 customerId 作為標頭參數來獲取特定客戶的帳戶詳細信息。我們本來會使用 customerId 作為查詢參數，但它是敏感信息，因此我們可以在標頭中傳遞它。
我們需要使用一個或多個 HTTP 狀態代碼映射響應。響應可以在 RAML 中以方案、示例、類型或描述的形式定義。
/accounts:
get:
description: Fetch all the accounts for customers.
headers:
customerId:
required: true
type: string
example: "323232"
maxLength: 20
responses:
200:
body:
application/json:
example: |
[{
"accountId": "32323232",
"accountType": "Current",
"accountName": "Mr. James John",
"currency": "USD",
"status": "Active"
}]在上面的 RAML 中，我們已經定義了成功 http 狀態代碼 200 的響應，但我們也可以定義錯誤 http 狀態代碼的響應，如 404、500，如下所示。
/accounts:
get:
description: Fetch all the accounts for customers.
headers:
customerId:
required: true
type: string
example: "323232"
maxLength: 20
responses:
200:
body:
application/json:
example: |
[{
"accountId": "32323232",
"accountType": "Current",
"accountName": "Mr. James John",
"currency": "USD",
"status": "Active"
}]
404:
body:
application/json:
example: {"message": "Resource Not Found", "errorCode": "404"}
500:
body:
application/json:
example: {"message": "Internal Server Error", "errorCode": "500"}當我們需要將body傳遞給API請求時，一般使用Request，它通常與POST，PUT，PATCH方法一起使用，我們可以在服務器上創建或修改資源。
/accounts:
get:
description: Fetch all the accounts for customers.
headers:
customerId:
required: true
type: string
example: "323232"
maxLength: 20
responses:
200:
body:
application/json:
example: |
[{
"accountId": "32323232",
"accountType": "Current",
"accountName": "Mr. James John",
"currency": "USD",
"status": "Active"
}]
404:
body:
application/json:
example: {"message": "Resource Not Found", "errorCode": "404"}
500:
body:
application/json:
example: {"message": "Internal Server Error", "errorCode": "500"}/accounts:
get:
description: Fetch all the accounts for customers.
headers:
customerId:
required: true
type: string
example: "323232"
maxLength: 20
responses:
200:
body:
application/json:
example: |
[{
"accountId": "32323232",
"accountType": "Current",
"accountName": "Mr. James John",
"currency": "USD",
"status": "Active"
}]
404:
body:
application/json:
example: {"message": "Resource Not Found", "errorCode": "404"}
500:
body:
application/json:
example: {"message": "Internal Server Error", "errorCode": "500"}
post:
description: Create Account for customer.
body:
application/json:
example: |
[{
"customerId": "6327632",
"accountId": "32323232",
"accountType": "Current",
"accountName": "Mr. James John",
"currency": "USD"
}]
responses:
200:
body:
application/json:
example: {"message": "Account Added Successfully"}在這個 RAML 入門中，我們已經看到了如何使用資源、請求、響應、URI 參數、查詢參數等來定義基本的 RAML。如果您注意到所有方法的模式保持不變，但每個方法的響應示例都不同。可以避免為每個方法編寫類似的模式和代碼。在我們的 RAML 進階中，我們將看到如何使用資源類型、庫、特征等來促進代碼的可重用性和更好的可讀性。
原文鏈接：https://blogs.mulesoft.com/dev-guides/api-design/restful-api-modeling-language-101/