# qooxdoo

## the new era of web development

### Navigation

- index
- next |
- previous |
- » Home »
- qooxdoo v1.5 documentation »
- Communication »

# REST (Representational State Transfer)

Note

This is an experimental feature.

`qx.io.rest.Resource` allows to encapsulate the specifics of a REST interface. Rather than requesting URLs with a specific HTTP method manually, a resource representing the remote resource is instantiated and actions are invoked on this resource. A resource with its actions can be configured declaratively or programatically.

## Configuring actions

Given a REST-like interface with URLs that comply to the following pattern.

    GET      /photos           index       display a list of all photos
    POST     /photos           create      create a new photo
    GET      /photos/:id       show        display a specific photo
    PUT      /photos/:id       update      update a specific photo
    DELETE   /photos/:id       destroy     delete a specific photo

Note `:id` stands for a placeholder replaced by

The specifics of the REST interface can be expressed declaratively.

    var description = {
      index: {
       method: "GET",
       url: "/photos"
      },

      create: {
        method: "POST",
        url: "/photos"
      },

      show: {
        method: "GET",
        url: "/photos/:id"
      },

      update: {
        method: "PUT",
        url: "/photos/:id"
      },

      destroy: {
        method: "DELETE",
        url: "/photos/:id"
      }
    }

    var photos = new qx.io.rest.Resource(description);

Or programatically.

    var photos = new qx.io.rest.Resource();
    photos.map("index", "GET", "/photos");

## Invoking actions

Once configured, actions can be invoked. They are invoked by calling a method that is dynamically added to the resource on configuration of the action.

    photos.index();
    // --> GET /photos

    photos.show({id: 1});
    // --> GET /photos/1

When an action is invoked, an appropriate request is configured and send automatically.

## Events

Events are fired by the resource when the request was sucessful or any kind of error occured. There are general resource events and action specific events. Handlers receive a `qx.event.type.Rest` event that, among other properties, includes the response.

    photos.index();
    photos.show({id: 1});

    // "success" is fired when any request associated to resource receives a response
    photos.addListener("success", function(e) {
      e.getAction();
      // --> "index" or "show"
    });

    // "indexSuccess" is fired when the request associated to the index action receives a response
    photos.addListener("indexSuccess", function(e) {
      e.getAction();
      // --> "index"
    });

## Helpers

Helpers make it easy to accomplish common tasks when working with requests.

- refresh(action) Resend request associated to action. Uses parameters given before.
- poll(action, params) Periodically invoke action.
- longPoll(action) Use Ajax long-polling to update whenever new data is available.

## Data binding

A `qx.data.store.Rest` store can be attached to an action. Whenever a response is received, the model property of the store is updated with the marshaled response.

    var store = new qx.data.store.Rest(photos, "index");
    var controller = new qx.data.controller.List();
    store.bind("model", controller, "model");
    photos.longPoll("index");