定义 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 规范。

请使用值为 Truewink.searchPolicyContinuedSearch 属性来修改此行为。如果没有任何子资源方法与请求相匹配,那么这将导致使用子资源定位器。

要启用该属性,请在已指定 wink.searchPolicyContinuedSearch 属性及值的模块的 WEB-INF 目录中包括属性文件。在应用程序模块的 web.xml 文件中,包括 init-param 元素以及值为 propertiesLocationparam-name 元素。 param-value 元素将指定属性文件的位置,例如 WEB-INF/my_wink.properties

以下示例说明了 web.xml 文件:
<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() { ...

过程

  1. 在应用程序中标识资源的类型。
    对于每个资源类,请标识现有的方法,或者创建要为每个受支持的 HTTP 方法调用的方法。对 HTTP 请求作出响应的方法也称为资源方法。对于资源类中的每个资源方法,请使用单一 JAX-RS HTTP 方法注释(例如 @javax.ws.rs.GET、@javax.ws.rs.POST、@javax.ws.rs.DELETE 或 @javax.ws.rs.PUT)对 Java™ 方法进行注释。例如,如果 BooksCollection 类支持 HTTP GET 方法,那么您可以创建方法并对其进行注释,如以下片段所示:
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
        @javax.ws.rs.GET
        public String getBooksCollection() {
            String str = /* Construct a String representation of the resource. */
            return str;
        }
    }
    使用 Web 浏览器或另一个 HTTP 客户机对 http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books URL 发出 HTTP GET 请求时,将调用先前的 getBooksCollection() 方法。
  2. 确保资源支持所需的 HTTP 方法。
    通常,每个资源有多个资源方法;例如:
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
        /* This is a database key. */
        private String ISBN;
    
        public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
            this.ISBN = ISBN;
        }
    
        @javax.ws.rs.GET
        public String retrieveSpecificBookInformation() {
            /* This code retrieves a book resource based on the ISBN key. */
        }
    
        @javax.ws.rs.PUT
        public String updateBookInformation(String updatedBookInfo) {
            /* This code updates the book resource based on ISBN key and the entity (message body) sent
             in the request that is stored in updatedBookInfo. */
        }
    
        @javax.ws.rs.DELETE
        public void removeBook() {
            /* This code deletes a book resource based on ISBN key. */
        }
    }
    使用 Web 浏览器或另一个 HTTP 客户机对 http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/<isbn_number> URL 发出 HTTP GET 请求时,将调用 retrieveSpecificBookInformation() 方法。向同一个 URL 发送 HTTP PUT 请求将调用 updateBookInformation 方法,并且,请求消息体中的任何内容都将作为 updatedBookInfo 对象的值进行传递。最后,向同一个 URL 发送 HTTP DELETE 请求将调用 removeBook() 方法。
    避免故障 避免故障: 根据 JAX-RS 规范,不得在同一个资源方法上放置多个 HTTP 方法注释,例如 @javax.ws.rs.POST 或 @javax.ws.rs.PUT。因为 HTTP 方法具有唯一定义的语义,所以请不要将一个资源方法用于多个 HTTP 方法。gotcha

结果

您已经为资源定义了有效的操作。


指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_httpmeth
文件名:twbs_jaxrs_defresource_httpmeth.html