15.11. RESTEasy JavaScript API

15.11.1. About the RESTEasy JavaScript API

RESTEasy can generate a JavaScript API that uses AJAX calls to invoke JAX-RS operations. Each JAX-RS resource class will generate a JavaScript object of the same name as the declaring class or interface. The JavaScript object contains each JAX-RS method as properties.

Example 15.18. Simple JAX-RS JavaScript API Example

@Path("foo")
public class Foo{
 @Path("{id}")
 @GET
 public String get(@QueryParam("order") String order, @HeaderParam("X-Foo") String header,
                   @MatrixParam("colour") String colour, @CookieParam("Foo-Cookie") String cookie){
  &
 }
 @POST
 public void post(String text){
 }
}
We can use the previous JAX-RS API in JavaScript using the following code: 
var text = Foo.get({order: 'desc', 'X-Foo': 'hello',
                    colour: 'blue', 'Foo-Cookie': 123987235444});
Foo.put({$entity: text});
Each JavaScript API method takes an optional object as single parameter where each property is a cookie, header, path, query or form parameter as identified by their name, or the API parameter properties. The properties are available here: Section 15.11.3, “RESTEasy Javascript API Parameters”.
Report a bug

15.11.2. Enable the RESTEasy JavaScript API Servlet

Summary

The RESTEasy JavaScript API is not enabled by default. Follow these steps to enable it using the web.xml file.

Procedure 15.6. Edit web.xml to enable RESTEasy JavaScript API

  1. Open the web.xml file of the application in a text editor.
  2. Add the following configuration to the file, inside the web-app tags: 
    <servlet>
    <servlet-name>RESTEasy JSAPI</servlet-name>
    <servlet-class>org.jboss.resteasy.jsapi.JSAPIServlet</servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>RESTEasy JSAPI</servlet-name>
    <url-pattern>/URL</url-pattern>
</servlet-mapping>
Report a bug

15.11.3. RESTEasy Javascript API Parameters

Table 15.5. Parameter Properties

Property Default Value Description
$entity   The entity to send as a PUT, POST request.
$contentType   The MIME type of the body entity sent as the Content-Type header. Determined by the @Consumes annotation.
$accepts */* The accepted MIME types sent as the Accept header. Determined by the @Provides annotation.
$callback   Set to a function (httpCode, xmlHttpRequest, value) for an asynchronous call. If not present, the call will be synchronous and return the value.
$apiURL   Set to the base URI of the JAX-RS endpoint, not including the last slash.
$username   If username and password are set, they will be used for credentials for the request.
$password   If username and password are set, they will be used for credentials for the request.
Report a bug

15.11.4. Build AJAX Queries with the JavaScript API

Summary

The RESTEasy JavaScript API can be used to manually construct requests. This topic covers examples of this behavior.

Example 15.19. The REST Object

The REST object can be used to override RESTEasy JavaScript API client behavior: 
// Change the base URL used by the API:
REST.apiURL = "http://api.service.com";

// log everything in a div element
REST.log = function(text){
 jQuery("#log-div").append(text);
};
The REST object contains the following read-write properties:
apiURL
Set by default to the JAX-RS root URL. Used by every JavaScript client API functions when constructing the requests.
log
Set to a function(string) in order to receive RESTEasy client API logs. This is useful if you want to debug your client API and place the logs where you can see them.

Example 15.20. The REST.Request Class

The REST.Request class can be used to build custom requests: 
var r = new REST.Request();
r.setURI("http://api.service.com/orders/23/json");
r.setMethod("PUT");
r.setContentType("application/json");
r.setEntity({id: "23"});
r.addMatrixParameter("JSESSIONID", "12309812378123");
r.execute(function(status, request, entity){
 log("Response is "+status);
});
Report a bug

15.11.5. REST.Request Class Members

Table 15.6. REST.Request Class

Member Description
execute(callback) Executes the request with all the information set in the current object. The value is passed to the optional argument callback, not returned.
setAccepts(acceptHeader) Sets the Accept request header. Defaults to */*.
setCredentials(username, password) Sets the request credentials.
setEntity(entity) Sets the request entity.
setContentType(contentTypeHeader) Sets the Content-Type request header.
setURI(uri) Sets the request URI. This should be an absolute URI.
setMethod(method) Sets the request method. Defaults to GET.
setAsync(async) Controls whether the request should be asynchronous. Defaults to true.
addCookie(name, value) Sets the given cookie in the current document when executing the request. This will be persistent in the browser.
addQueryParameter(name, value) Adds a query parameter to the URI query part.
addMatrixParameter(name, value) Adds a matrix parameter (path parameter) to the last path segment of the request URI.
addHeader(name, value) Adds a request header.
Report a bug