在 RESTful 应用程序中定义资源的 URI 模式
具象状态传输 (REST) 服务依赖于处理资源。RESTful 服务的资源可寻址,并且 URL 是在 REST 中实现可寻址性的主要方法。
开始之前
标识应用程序中要作为 RESTful 服务呈示的资源。
关于此任务
URL 用来指定资源的位置。服务器与客户机之间的交互依赖于向 URL 发出 HTTP 操作。定义 URL 模式至关重要,这是因为,URL 通常具有很长的生存期,因此客户机在最初发现资源之后的很长时间内都可以直接对该资源进行寻址。
在 Web 浏览器中输入地址时,通常使用 URL,例如 http://www.ibm.com/ 或 http://www.example.com/bookstore/books/ISBN123。虽然 URL 不必被用户理解,但是,RESTful 服务以可理解的模式来提供逻辑 URL 有助于提高客户机应用程序开发者的工作效率。
RESTful 客户机使用 URL 来维护资源。每个资源都必须具有自己的唯一 URL。某些 URL 模式具有追加了唯一标识的集合路径。例如,您可以使用 http://www.example.com/bookstore/books 作为集合资源 URL,使用 http://www.example.com/bookstore/books/ISBN123 作为唯一的书籍资源 URL,并可以使用 http://www.example.com/bookstore/books/ISBN123/authors 来检索用于描述 ISBN123 作者的集合资源。
应用程序开发者必须谨慎地考虑 URL 的详细程度,这是因为,它会影响应用程序的用法以及性能。例如,可以包括书籍的作者信息作为书籍资源的组成部分,也可以将作者信息定义为具有自己的 URL(在书籍资源中引用此 URL)的独特资源。根据资源的复用情况,为作者信息定义独立的资源可能效率更高,这样,该作者编写另一书籍时,就可以在书籍资源的超链接中引用该作者信息资源。
向客户机提供初始 URL 之后,将可以通过解析当前资源来发现后续的相关请求。在书籍示例中,对 http://www.example.com/bookstore/books/ 发出的 GET 请求将检索书籍 URL 列表,该列表可能包含 http://www.example.com/bookstore/books/ISBN123。
由于系统依赖于资源可用,因此 URL 的生存期通常较长。因为 HTTP 具有用于执行重定向的内置状态码,例如 301 永久移动代码和 307 临时重定向代码,所以使用了高速缓存的用户和客户机通常先复用先前发现的 URL。另外,您可以考虑在 URL 模式中包括版本标识,例如 http://www.example.com/bookstore/v2/books/ISBN123。就像使用 Java™ 代码来定义接口时涉及的规划一样,由于 URL 模式的生存期较长,因此您务必谨慎地选择 URL 模式。
在 Java API for RESTful Web Services (JAX-RS) 中,必须对 Java 类文件或 Java 方法添加 @Path 注释以定义资源的相对 URL。您可以使用 JAX-RS 子资源定位器和子资源方法来定义资源。请使用 URL 中的参数(例如路径参数或矩阵参数)来标识资源。
@Path 注释中的值定义资源的完整 URL 的相对部分。基本 URL 从域、端口、应用程序模块上下文根以及应用程序模块的 web.xml 文件中的任何 URL 模式映射派生。例如,如果域是 www.example.com,端口是 9060,模块上下文根是 example,Servlet URL 模式是 store/*,那么 @Path 注释的值将是 /bookstore/books。完整的 URL 是:http://www.example.com:9060/example/store/bookstore/books。
过程
结果
您已创建用于标识 RESTful 服务的资源的 URL。通过在应用程序设计阶段提早考虑 URL 模式问题,RESTful 服务能够长时间地提高其可用性和价值。
下一步做什么
位于所定义的 URL 处的资源存在。但是,该资源还没有任何用于处理 HTTP 方法操作(例如 GET、POST、PUT 或 DELETE)的方法。请参阅“为 RESTful 应用程序定义资源方法”以进一步了解如何使用受支持的 HTTP 方法来定义资源的功能。