== AJAX Client

RESTEasy resources can be accessed in JavaScript using AJAX using a proxy API generated by RESTEasy.

=== Generated JavaScript API

RESTEasy can generate a JavaScript API that uses AJAX calls to invoke {spec-name} operations.

.First {spec-name} JavaScript API example
====
Let's take a simple {spec-name} API:

[source,java]
----
@Path("orders")
public class Orders {
    @Path("{id}")
    @GET
    public String getOrder(@PathParam("id") String id) {
        return "Hello "+id;
    }
}
----

The preceding API would be accessible using the following JavaScript code: 

[source,javascript]
----
var order = Orders.getOrder({id: 23});
----
====

==== JavaScript API servlet

In order to enable the JavaScript API servlet the user must configure it in the web.xml file as such: 

[source,xml]
----
<web-app>
    <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>/rest-js</url-pattern>
    </servlet-mapping>
</web-app>
----

==== JavaScript API usage

Each {spec-name} resource class will generate a JavaScript object of the same name as the declaring class (or interface), which will contain every {spec-name} method as properties.

.Structure of {spec-name} generated JavaScript
====
For example, if the  resource X defines methods Y and Z: 

[source,java]
----
@Path("/")
public interface X{
    @GET
    String Y();
    @PUT
    void Z(String entity);
}
----

Then the JavaScript API will define the following functions: 

[source,javascript]
----
var X = {
 Y : function(params){},
 Z : function(params){}
};
----
====

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 following special parameters: 

[WARNING]
====
The following special parameter names are subject to change.
====

[cols="1,1,1", options="header"]
|===
|Property Name
|Default
|Description

|$entity
|
|The entity to send as a PUT, POST request.

|$contentType
|As determined by `@Consumes`.
|The MIME type of the body entity sent as the Content-Type header.

|$accepts
|Determined by `@Provides`, defaults to */*.
|The accepted MIME types sent as the Accept header.

|$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
|Determined by container
|Set to the base URI of your {spec-name} 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.
|===

.Using the API
====
Here is an example of {spec-name} API:

[source,java]
----
@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 {spec-name} API in JavaScript using the following code:

[source,javascript]
----
var text = Foo.get({order: 'desc', 'X-Foo': 'hello',
                    colour: 'blue', 'Foo-Cookie': 123987235444});
Foo.put({$entity: text});
----
====

==== Work with @Form

`@Form` is a RESTEasy specific annotation that allows the user to re-use any `@*Param` annotation within an injected class.
The generated JavaScript API will expand the parameters for use automatically.
Support we have the following form: 

[source,java]
----
public class MyForm {
    @FormParam("stuff")
    private String stuff;

    @FormParam("number")
    private int number;

    @HeaderParam("myHeader")
    private String header;
}
----

And the resource is like:

[source,java]
----
@Path("/")
public class MyResource {

    @POST
    public String postForm(@Form MyForm myForm) {}

}
----

Then the method can be called from JavaScript API like following:

[source,javascript]
----
MyResource.postForm({stuff:"A", myHeader:"B", number:1});
----

Also, `@Form` supports prefix mappings for lists and maps:

[source,java]
----
public static class Person {
    @Form(prefix="telephoneNumbers") List<TelephoneNumber> telephoneNumbers;
    @Form(prefix="address") Map<String, Address> addresses;
}

public static class TelephoneNumber {
    @FormParam("countryCode") private String countryCode;
    @FormParam("number") private String number;
}

public static class Address {
    @FormParam("street") private String street;
    @FormParam("houseNumber") private String houseNumber;
}

@Path("person")
public static class MyResource {
    @POST
    public void postForm(@Form Person p) {}
}
----

From JavaScript the API could be called like this:

[source,javascript]
----
MyResource.postForm({
    telephoneNumbers:[
        {"telephoneNumbers[0].countryCode":31},
        {"telephoneNumbers[0].number":12345678},
        {"telephoneNumbers[1].countryCode":91},
        {"telephoneNumbers[1].number":9717738723}
    ],
    address:[
        {"address[INVOICE].street":"Main Street"},
        {"address[INVOICE].houseNumber":2},
        {"address[SHIPPING].street":"Square One"},
        {"address[SHIPPING].houseNumber":13}
    ]
});
----

==== MIME types and unmarshalling.

The Accept header sent by any client JavaScript function is controlled by the $accepts parameter, which overrides the @Produces annotation on the {spec-name} endpoint.
The returned value however is controlled by the Content-Type header sent in the response as follows: 

[cols="1,1", options="header"]
|===
|MIME
|Description

|text/xml,application/xml,application/*+xml
|The response entity is parsed as XML before being returned. The return value is thus a DOM Document.

|application/json
|The response entity is parsed as JSON before being returned. The return value is thus a JavaScript Object.

|Anything else
|The response entity is returned raw.
|===

.Unmarshalling example
====
The RESTEasy JavaScript client API can automatically unmarshall JSON and XML: 

[source,java]
----
@Path("orders")
public interface Orders {

    @XmlRootElement
    class Order {
        @XmlElement
        private String id;

        public Order(){}

        public Order(String id){
            this.id = id;
        }
        @Path("{id}/xml")
        @GET
        @Produces("application/xml")
        public Order getOrderXML(@PathParam("id") String id){
            return new Order(id);
        }

        @Path("{id}/json")
        @GET
        @Produces("application/json")
        public Order getOrderJSON(@PathParam("id") String id){
            return new Order(id);
        }
    }
}
----

Let's look at what the preceding {spec-name} API would give on the client side:

[source,javascript]
----
// this returns a JSON object
var orderJSON = Orders.getOrderJSON({id: "23"});
orderJSON.id == "23";

// this one returns a DOM Document whose root element is the order, with one child (id)
// whose child is the text node value
var orderXML = Orders.getOrderXML({id: "23"});
orderXML.documentElement.childNodes[0].childNodes[0].nodeValue == "23";
----
====

==== MIME types and marshalling.

The Content-Type header sent in the request is controlled by the $contentType parameter which overrides the @Consumes annotation on the {spec-name} endpoint.
The value passed as entity body using the $entity parameter is marshalled according to both its type and content type: 

[cols="1,1,1", options="header"]
|===
|Type
|MIME
|Description

|DOM Element
|Empty or text/xml,application/xml,application/*+xml
|The DOM Element is marshalled to XML before being sent.

|JavaScript Object (JSON)
|Empty or application/json
|The JSON object is marshalled to a JSON string before being sent.

|Anything else
|Anything else
|The entity is sent as is.
|===

.Marshalling example
====
The RESTEasy JavaScript client API can automatically marshall JSON and XML: 

[source,java]
----
@Path("orders")
public interface Orders {

    @XmlRootElement
    public static class Order {
        @XmlElement
        private String id;

        public Order(){}

        public Order(String id){
            this.id = id;
        }
    }

    @Path("{id}/xml")
    @PUT
    @Consumes("application/xml")
    default void putOrderXML(Order order){
        // store order
    }

    @Path("{id}/json")
    @PUT
    @Consumes("application/json")
    default void putOrderJSON(Order order){
        // store order
    }
}
----

Let's look at what the preceding {spec-name} API would give on the client side:

[source,javascript]
----
// this saves a JSON object
Orders.putOrderJSON({$entity: {id: "23"}});

// It is a bit more work with XML
var order = document.createElement("order");
var id = document.createElement("id");
order.appendChild(id);
id.appendChild(document.createTextNode("23"));
Orders.putOrderXML({$entity: order});
----
====

=== Using the JavaScript API to build AJAX queries

The RESTEasy JavaScript API can also be used to manually construct your requests. 

==== The REST object

The REST object contains the following read-write properties: 

[cols="1,1", options="header"]
|===
|Property
|Description

|apiURL
 Set by default to the {spec-name} 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 to debug the client API and
place the logs where you can see them.
|===

.Using the REST object
====
The REST object can be used to override RESTEasy JavaScript API client behaviour: 

[source,javascript]
----
// 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.Request class

The REST.Request class is used to build custom requests.
It has the following members: 

[cols="1,1,1", options="header"]
|===
|Member
|Description

|execute(callback)
|Executes the request with all the information set in the current object. The value is never returned but passed to the optional argument callback.

|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)
|ets the given cookie in the current document when executing the request. Beware that this will be persistent in your 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.
|===

.Using the REST.Request class
====
The REST.Request class can be used to build custom requests: 

[source,javascript]
----
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);
});
----
====

=== Caching Features

RESTEasy AJAX Client works well with server side caching features.
But the buggy browsers cache will  always prevent the function to work properly.
To use the RESTEasy caching feature with its AJAX client, enable the 'antiBrowserCache' option: 

[source,javascript]
----
REST.antiBrowserCache = true;
----

The above setting should be set once before calling any APIs. 