摘要：REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，用于构建网络服务。REST API 是遵循 REST 架构风格的接口，通过标准的 HTTP 方法（如 GET、POST、PUT、DELETE）与客户
REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，用于构建网络服务。REST API 是遵循 REST 架构风格的接口，通过标准的 HTTP 方法（如 GET、POST、PUT、DELETE）与客户端进行交互。
Microsoft 提供了一套 REST API 指南，旨在设计一致性高、易用性强的 RESTful 接口。指南广泛应用于 Microsoft 的云服务（如 Azure 和 Microsoft Graph）以及其他产品中。
Microsoft 的 REST API 指南基于以下核心原则：
2.1 一致性• 统一的资源命名：所有资源应使用一致的命名规则，通常为小写字母和连字符（-）。
• 标准化的 HTTP 方法：使用标准的 HTTP 动词来表示操作，如：
• GET：获取资源。
• POST：创建资源。
• PUT：更新资源。
• DELETE：删除资源。
2.2 可预测性• 清晰的 URL 结构：API 的 URL 应清晰地表示资源的层次关系。如：
HTTPS://api.example.com/users/{userId}/orders/{orderId}• 一致的响应格式：API 应返回一致的 JSON 格式响应，包含标准的状态码和错误信息。
2.3 可扩展性• 版本控制：通过 URL 或 HTTP 头部实现 API 的版本控制，例如：
或使用 Accept头部：
Accept: application/vnd.example.v1+json2.4 安全性• 身份验证：推荐使用 OAuth 2.0 或其他安全协议进行身份验证。
• HTTPS：所有 API 通信必须通过 HTTPS 加密。
3.1 资源命名• 使用名词表示资源，避免使用动词。
• 资源名称应为复数形式，如：
/users/orders3.2 HTTP 方法的使用
• GET：获取资源或资源集合。
• POST：创建新资源。
• PUT：更新资源（幂等操作）。
• PATCH：部分更新资源。
• DELETE：删除资源。
3.3 状态码API 应返回标准的 HTTP 状态码以表示操作结果：
• 200 OK：请求成功。
• 201 Created：资源创建成功。
• 204 No Content：请求成功，但无返回内容。
• 400 Bad request：请求无效。
• 401 Unauthorized：未授权。
• 404 Not Found：资源未找到。
• 500 Internal Server Error：服务器内部错误。
3.4 错误处理错误响应应包含详细的错误信息，通常以 JSON 格式返回。如：
{"error":{
"code":"InvalidRequest",
"message":"The request is invalid.",
"details":[
{
"target":"email",
"message":"The email address is invalid."
}
]
}
}3.5 分页
对于返回大量数据的 API，推荐使用分页机制。如：
GET /users?page=1&pageSize=50响应中应包含分页信息：
{"data":[...],
"pagination":{
"currentPage":1 ,
"pageSize":50 ,
"totalPages":10 ,
"totalItems":500
}
}3.6 版本控制
API 的版本控制可以通过以下方式实现：
• URL 路径：
/v1/users• HTTP 头部：
Accept: application/vnd.example.v1+json操作HTTP 方法URL描述获取所有用户
GET
/users获取用户列表
获取单个用户
GET
/users/{userId}获取指定用户详情
创建新用户
POST
/users创建新用户
更新用户信息
/users/{userId}更新用户信息
删除用户
DELETE
/users/{userId}删除用户
4.2 示例[ApiController][Route("api/v1/users")]
publicclassUsersController:ControllerBase
{
[HttpGet]
publicIActionResultGetUsers
{
varusers =newListobject
{
new{ Id = 1, Name = "Alice", Email = "alice@example.com" },
new{ Id = 2, Name = "Bob", Email = "bob@example.com" }
};
returnOk(users);
}
[HttpGet("{id}")]
publicIActionResultGetUser(intid)
{
varuser =new{ Id = id, Name = "Alice", Email = "alice@example.com" };
returnOk(user);
}
[HttpPost]
publicIActionResultCreateUser([FromBody]objectuser)
{
returnCreated("/api/v1/users/3", user);
}
[HttpPut("{id}")]
publicIActionResultUpdateUser(intid, [FromBody]objectuser)
{
returnNoContent;
}
[HttpDelete("{id}")]
publicIActionResultDeleteUser(intid)
{
returnNoContent;
}
}
1. 一致性：通过统一的设计规范，减少了开发和使用 API 的学习成本。
2. 可扩展性：支持版本控制和分页，便于扩展和维护。
3. 安全性：推荐使用 HTTPS 和 OAuth 2.0，确保数据传输安全。
4. 易用性：清晰的 URL 结构和标准化的错误响应，提升了开发者体验。
Microsoft REST API 指南提供了一套清晰的设计规范，帮助构建一致性高、可扩展性强的 RESTful 接口。在实际开发中，遵循这些指南可以显著提升 API 的可维护性和用户体验。
来源：opendotnet
