定义 RESTful 应用程序的资源方法
各个资源可以使用受支持的 HTTP 方法来定义它们的功能。在具象状态传输 (REST) 服务中,受支持的方法是 GET、PUT、DELETE 和 POST。通常,所有操作都通过对资源使用其中一个预定义的 HTTP 方法来完成。
开始之前
了解预定义的 HTTP 方法及其已知属性。一些 HTTP 方法是安全的(这表示发出请求不会更改资源)或者幂等的(这表示多次调用操作并不会更改结果)。虽然 HTTP 方法被定义为具有特定属性,但服务实现遵循定义。请参阅 HTTP 方法定义信息,以便进一步了解 HTTP 的常用方法集。
关于此任务
客户机使用 HTTP 方法来执行某些操作。与每个系统都定义独特接口的其他分布式系统不同,基于 HTTP 的 RESTful 系统主要信赖于预定义的方法。四个最常用的方法是 GET、PUT、DELETE 和 POST。资源不必允许所有客户机使用所有 HTTP 方法。
HTTP GET 方法检索资源表示。它是安全的,并且是幂等的。重复的 GET 请求不会更改任何资源。
HTTP PUT 方法通用用来更新资源或者在已知的 URL 处创建新实体。必须更新或创建资源时,请对资源 URL 发出 HTTP PUT 方法并指定新的资源数据作为请求实体(也称为消息体)。HTTP PUT 方法是幂等的,因此,对同一个 URL 发出的多个包含同一实体的相同 PUT 请求将产生相同的结果,就像只发出了一个 PUT 请求一样。此方法假定未发出其他相关的请求。
HTTP DELETE 方法移除特定 URL 处的资源。
在不知道最终资源 URL 的情况下在集合中创建资源时,通常使用 HTTP POST 方法。例如,管理员对 /users 集合资源发出 POST 请求,该请求将创建具有唯一标识(例如 1234567890)的用户。然后,将该唯一标识用作 URL 路径的组成部分,以便描述新的用户资源,例如 /users/1234567790。它既不是安全的也不是幂等的。在本例中,对 /users 集合发出的多个 POST 请求可以继续创建新的唯一标识并将这个新标识添加到用户集合中,即使用户的信息相同也如此。
由于大多数 RESTful 服务使用用于提供预期结果的周知 HTTP 方法,因此您可以轻松地创建客户机。RESTful 服务开发者可以利用 HTTP 方法的预期行为。资源方法还可以使用参数(例如路径参数、查询参数或矩阵参数)来标识资源。要了解更多信息,请参阅“定义资源的请求表示中的参数用法”。
(可选)如果您有相同资源类中具有相同值的子资源方法和子资源定位器方法(具有 @Path 注释),那么当确定缺省情况下要调用的方法时,将不考虑子资源定位器。这符合 JAX-RS 规范。
请使用值为 True 的 wink.searchPolicyContinuedSearch 属性来修改此行为。如果没有任何子资源方法与请求相匹配,那么这将导致使用子资源定位器。
要启用该属性,请在已指定 wink.searchPolicyContinuedSearch 属性及值的模块的 WEB-INF 目录中包括属性文件。在应用程序模块的 web.xml 文件中,包括 init-param 元素以及值为 propertiesLocation 的 param-name 元素。 param-value 元素将指定属性文件的位置,例如 WEB-INF/my_wink.properties。
<servlet>
...
...
<init-param>
<param-name>propertiesLocation</param-name>
<param-value>/WEB-INF/my_wink.properties</param-value>
</init-param>
</servlet>
以下示例说明了 WEB-INF/my_wink.properties 属性文件:wink.searchPolicyContinuedSearch=true
在以下代码示例中,请求 URL 以 sayhello 结尾,但是该请求包含 POST 而不是 GET,因此会返回 HTTP 405 Method Not Allowed 错误消息。请确保所发送的 HTTP 方法与方法注释相匹配,以避免返回 405。
@javax.ws.rs.Path("helloworld")
public class SampleResource {
...
@javax.ws.rs.Path("sayhello")
@javax.ws.rs.GET
public String getHello() { ...
过程
结果
您已经为资源定义了有效的操作。