Identifying HTTP Methods

An HTTP request method is a verb which specifies the action to be performed on a resource. The resource is identified using the complete URI and a combination of query parameters, form parameters or request body. Eight such methods are supported: GET, POST, PATCH, PUT, DELETE, HEAD, TRACE and OPTIONS. Request definitions that use these methods are identified by the annotation of the same name.

####1. HTTP GET

GET requests are used for retrieving a resource identified by the URI. It can use a query string to further filter the identity of the resource. A GET request should not possess a payload in its body; hence any @FormParam, @FormParams and @Entity annotations are forbidden.

@GET("/repos/sahan/RoboZombie/issues")
List<Issue> getIssues(@QueryParam("state") String state);

####2. HTTP POST

POST requests are used to update the a resource identified by the URI. The request body should contain the update version of the resource as the payload. A POST request is allowed to use @FormParam, @FormParams and @Entity to describe the updated resource. Some servers may create the resource if it doesn't exist already and reply with 210 (Created).

@POST("/gists")
void postGist(@Entity Gist gist);

####3. HTTP PATCH

PATCH requests are relatively new as was introduced in RFC 5789. They are used to apply partial updates to the resource identified by the URI. Like POST, if the URI does not point to an existing resource, the resource may be created instead. The patched resource is sent as a request payload using the @Entity annotation.

@PATCH("/gists/{id}")
void patchGist(@PathParam("id") String id, @Entity Gist gist);

@FormParam and @FormParams are permissible.

####4. HTTP PUT

PUT requests are used to create a new resource at the location identified by the URI. The resource to be created is sent within the request body using an @Entity annotation.

@PUT("/repos/sahan/RoboZombie/issues/{no}/labels")
void putLabels(@PathParam("no") String no, @Entity List<String> labels);

####5. HTTP DELETE

DELETE requests are used to remove the resource identified by the URI from the server. These requests should not contain a payload in its body; hence any @FormParam, @FormParams and @Entity annotations are forbidden.

@DELETE("/repos/sahan/RoboZombie/issues/{no}/labels")
void deleteAllLabels(@PathParam("no") String no);

####6. HTTP HEAD

HEAD requests are used to retrieve meta-information about the resource identified by the URI. These requests are quite similar to GET requests with the exception that the response does not include a payload in its body. A HEAD request may not contain a request body and the required meta-information is contained within the response headers.

@HEAD("/user/repos")
void queryAuthScheme(@Header("WWW-Authenticate") StringBuilder authResponseHeader);

####7. HTTP TRACE

TRACE requests are used to follow a request to the server and use that information for testing and diagnostics. A TRACE request may not contain a request body.

@TRACE("/feeds")
void queryGateways(@Header("Via") StringBuilder viaResponseHeader);

####8. HTTP OPTIONS

OPTIONS requests are used for retrieving information about the communication options available to the server regarding the resource identified by the URI. An OPTIONS request may not contain a request body.

@OPTIONS("/feeds")
void queryContentType(@Header("Content-Type") StringBuilder contentTypeResponseHeader);