RESTful API 建模语言入门

在这篇博客中，我们将看到如何使用 Restful API 建模语言设计 REST API。在实现 API 之前设计 API 并从架构师、用户或业务利益相关者那里获得反馈非常重要。它为我们提供了在设计阶段修改 API 的优势，其中包括请求消息、响应消息、标头或查询参数等。

API 设计始终是构建应用程序的第一步。定义正确的资源、请求和响应模型、标头、查询参数、错误代码和方法以设计可靠的 API 非常重要。这种方法也称为设计优先方法。

什么是 RESTful API 建模语言？

RESTful API 建模语言是一种 API 设计语言，它允许开发人员利用完整的 API 设计生命周期，这意味着他们可以直观地设计他们的 API、测试它们并获得用户反馈，而无需编写任何代码。RESTful API 建模语言以人类可读的格式（纯文本）描述 API。

RESTful API 建模语言是一种基于 YAML 的语言，用于描述 RESTful API。它提供了描述 RESTful 或实际 RESTful API 所需的所有信息。

RESTful API建模语言能够描述不遵守所有 REST 限制（因此得名“实际上的 RESTful”）的API。它鼓励重用、启用发现和模式共享，并旨在实现基于价值的最佳实践的涌现。

在这里，我们将考虑与银行 API 和编写 RESTful API 建模语言相关的用例：

• 列出客户的所有帐户 （GET/accounts)
• 列出单个帐户 （GET/accounts/{accountId})
• 创建帐户 （POST/accounts)
• 列出帐户 （GET/accounts/{accountId}/balances） 的余额)
• 列出账户的所有交易并根据日期范围进行筛选 （GET /accounts/{accountId}/transactions?fromTransactionDate=2021-07-01&toTransactionDate=2021-08-01)
• 列出帐户的单个事务 （GET /accounts/{accountId}/transactions/{transactionId})

Root

在 RESTful API 建模语言中，我们需要使用一些基本信息来定义Root，例如 API 支持的标题、版本、baseUri、协议和媒体类型。

#%RAML 1.0
title: Open Banking API
version: v1
baseUri: http://api.openbanking.com/{version}

mediaType:
- application/json
- application/xml

以下是我们在上面代码中声明的Root属性的描述：

• API 标题： API 的标题应为 API 的简短纯文本标签。
• 版本： 每个 API 都应具有相应的字母数字版本。
• 协议： 可选协议节点指定 API 支持的协议。如果未显式指定协议节点，则使用 baseUri 节点中的协议。

最佳做法是在Root级别定义标题、版本、baseUri、mediaType 和协议。RESTful API 建模语言文件名采用小写的字母数字字符，使用 kebab 大小写（即连字符分隔）。

资源

这是您需要定义 API 资源的重要步骤之一，资源以 （/） 开头。使用这些资源，您可以控制使用者或客户端如何使用 API。

括在大括号中的资源是一个 uri 参数。URI 参数（Path Param）基本上用于标识一个或多个特定资源。

作为最佳实践，资源名称必须始终是复数形式，并且它应该是名词而不是动词。

/accounts:
/{accountId}:
/balances:
/transactions:
/{transactionId}:

方法

REST API 支持多种 HTTP 方法，如下所示：

• GET：从服务器获取信息
• POST：在服务器上创建资源
• DELETE：从服务器中删除资源
• PUT：在服务器上创建或更新新的或现有的资源
• PATCH：修改服务器上的资源

我们可以为每个资源定义方法，并且每个资源可以有多个 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/