jquery.rest

by alassek

alassek / jquery.rest

REST helpers for jQuery to ease AJAX interaction with Rails

125 Stars 15 Forks Last release: Not found MIT License 40 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

jQuery.rest

A plugin to ease AJAX interaction with RESTful APIs such as Rails

Accepted Parameters

There are four public jQuery methods created by this plugin:

jQuery.create
jQuery.read
jQuery.update
jQuery.destroy

Each function accepts 1-4 parameters:

url [, data [, success [, error ] ] ]
  • url
    : (string) The url of the resource, which can include a dynamically populated value surrounded by {braces}
  • data
    : (hash | string) The data to post to the resource, also used to populate dynamic values.
    • In GET requests, data will be added to the url as query-string parameters
  • success
    : (function) The success callback
  • error
    : (function) The error callback

In addition to these parameters, you can simply pass a standard jQuery.Ajax options object instead as the only parameter.

Breaking change: success, error callback parameters

Both

success
and
error
callbacks are passed a
headers
object whose key-value pairs correspond to the HTTP Response headers.
  • success
    • data
      : The reponse data for the request
    • headers
    • xhr
  • error
    • xhr
    • headers

In addition to being passed to the callbacks, this parsed object is attached directly to the

xhr
as well.
var xhr = $.read('/tasks.json');
xhr.responseHeaders
// => Object {
// =>   Connection: "close",
// =>   Content-Length: "543",
// =>   Content-Type: "application/json;charset=utf-8"
// => }

This was inspired by the GitHub API which makes use of custom HTTP response headers and the fact that

xhr.getAllReponseHeaders()
is next to useless.

Example

Create a new 'task' record with a success callback

$.create(
  '/tasks',
  { description: 'follow up after meeting' },
  function (reponse) {
    alert('successfully added task.');
  }
);
// => [POST] /tasks
// => authenticity_token: K06+3rRMlMuSoG60+Uw6UIo6UsZBbtIIPu2GaMbjf9s=
// => description: follow up after meeting

Read an existing 'account' object and add it to the page (this callback is making some assumptions about your controller -- YMMV)

$.read(
  '/accounts/2486',
  function (response) {
    $('ul#accounts').append(response);
  }
);
// => [GET] /accounts/2486

Update an existing 'task' record with ID 54

$.update(
  '/tasks/54',
  { description: 'lunch tomorrow after 1pm' }
);
// => [PUT] /tasks/54
// => authenticity_token: K06+3rRMlMuSoG60+Uw6UIo6UsZBbtIIPu2GaMbjf9s=
// => description: lunch tomorrow after 1pm

Update a nested 'task' record using dynamic IDs

$.update(
  '/accounts/{account_id}/tasks/{id}',
  { id: 54, account_id: 11387, description: 'lunch tomorrow after 1pm' }
);
// => [PUT] /accounts/11387/tasks/54
// => authenticity_token: K06+3rRMlMuSoG60+Uw6UIo6UsZBbtIIPu2GaMbjf9s=
// => description: lunch tomorrow after 1pm

Delete a 'task' object with ID 54

$.destroy('/tasks/54')
// => [DELETE] /tasks/54

Delete a 'task' object using alternate syntax

$.destroy({
  url: '/tasks/54',
  success: function (response) {
    alert('successfully deleted task.');
  }
});
// => [DELETE] /tasks/54

Using $.Deferred

jQuery.rest helpers all support the new jQuery.Deferred syntax:

$.read('/tasks/{id}.json', { id: 34 }).then(function (task) { /* do something with task */ });

Setting Content-Type header

jQuery.rest will look for a content-type setting in three places:

  1. options.contentType
    if you're using the alternate syntax
  2. or else
    $.restSetup.contentType
  3. or else it will look for a
    json
    or
    xml
    extension on the url resource.

If all three of those sources fail, it will use the browser's default.

Setting csrf token & method parameter

There is a global object called $.restSetup that you can modify in your application's Javascript startup to match your environment.

$.restSetup.csrfParam
and
$.restSetup.csrfToken
define how the authenticity token is formatted. By default they are loaded from meta tags named
csrf-param
and
csrf-token
. Set them manually if you are unable to follow this convention.

PUT and DELETE verbs are used by default, but if you need to tunnel them through the POST method instead:

$.restSetup.useMethodOverride = true;

$.restSetup.methodParam
can be changed if you pass back the REST method differently. Defaults to
_method
.

Example:

$.extend($.restSetup, {
  useMethodOverride: true,
  methodParam: 'action',
  csrfParam: '_csrf',
  csrfToken: encodeURIComponent(AUTH_TOKEN)
});

-- or --

$.destroy('/tasks/54');
// => [POST] /tasks/54
// => action: delete
// => _csrf: K06+3rRMlMuSoG60+Uw6UIo6UsZBbtIIPu2GaMbjf9s=

Customize HTTP verbs

By default, jQuery.rest conforms to Rails' HTTP verbs: POST to create, PUT to update, DELETE to destroy.

Not all RESTful APIs behave this way, and some argue that this isn't actually REST. If you need to override the methods being used, you can customize

$.restSetup.verbs
.
$.restSetup.verbs.update = 'PATCH';
$.update(
  '/accounts/{account_id}/tasks/{id}',
  { id: 54, account_id: 11387, description: 'lunch tomorrow after 1pm' }
);
// => [PATCH] /accounts/11387/tasks/54
// => authenticity_token: K06+3rRMlMuSoG60+Uw6UIo6UsZBbtIIPu2GaMbjf9s=
// => description: lunch tomorrow after 1pm

(

$.read
will of course always use GET, but the others can be changed to anything you desire.)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.