如何在 RESTful Web 服务中表示资源

RESTful Web 服务使用一些约定来表示和操作资源。在 RESTful API 中，每个资源都可以由独一无二的 URL、HTTP 方法和 MIME 类型组成。这些组件将细节与上下文分离，使得客户端和服务器能够更直接和简单地通信。本文将向程序员介绍 RESTful Web 服务中如何表示资源。

表示资源的 URL

在 RESTful API 中，URL 必须是独一无二的，以使得每个资源都可以通过一个固定的 URL 访问。这意味着，URL 确定了唯一的资源，而资源代表了命名空间、标识符、定位器或唯一的識別碼。URL 应该只表示一种资源，保持单一性。以下是如何表示资源的 URL 的示例：

1. 使用名词表示资源。
2. 对于单个资源，可以使用其 ID 或名称来区分。
3. 对于集合资源，可以使用它们的名称和其他过滤器。
4. 有些情况下，可以使用多个名称组合成 URL 更好地表示资源的关系。
5. 避免使用可能会改变的信息（如时间戳）作为 URL 的一部分。

以下是关于 URL 表示资源的示例：

例子 | 说明 ----|---- /api/users | 表示用户集合的 URL /api/users/1 | 表示 ID 为 1 的用户的 URL /api/users?age=18 | 表示筛选年龄为 18 的用户的 URL /api/users/1/friends | 表示 ID 为 1 的用户的朋友集合的 URL

HTTP 方法

在 RESTful API 中，HTTP 方法表示了一种状态转换或操作，用于对资源进行读取、创建、更新或删除操作。以下是 RESTful Web 服务中常用的 HTTP 方法：

• GET：用于获取资源的信息。
• POST：用于创建资源。
• PUT：用于更新资源。
• DELETE：用于删除资源。

HTTP 方法应与 URL 中的资源类型相对应。例如，使用 PUT 方法来更新资源，可以表示其期望更新资源，而使用 POST 方法来更新资源，则可能会导致服务端创建一个新的资源。

MIME 类型

MIME (Multipurpose Internet Mail Extensions) 类型表示由服务器返回的表示形式。当客户端发起请求时，可以请求服务器以数据的某一种 MIME 类型返回资源，如 text/html、application/json 等。在客户端获取到服务器返回的响应后，根据 MIME 类型对响应进行解析，并进行相应的处理。

在 RESTful API 中，服务器可以以多种 MIME 类型返回数据，客户端在请求中设置 Accept 头部来指定期望获取的 MIME 类型，以此告知服务端希望以何种形式返回数据。

总结

在 RESTful Web 服务中，每个资源都应该有一个通过独特的 URL 进行标识和访问。使用 HTTP 方法来表示状态转换或操作，以及 MIME 类型来表示由服务器返回的表示形式。合理使用 RESTful API 可以简化 Web 服务的开发和操作，提高客户端和服务器端交互的效率。

参考文献：

• RESTful API 设计指南
• [RESTful API Best Practices and Common Pitfalls][2]

[2]: https://blog.restcase.com/restful-api-best-practices-common-pitfalls/