REST helpers for jQuery to ease AJAX interaction with Rails
A plugin to ease AJAX interaction with RESTful APIs such as Rails
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.
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.
Both
successand
errorcallbacks are passed a
headersobject 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
xhras 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.
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
jQuery.rest helpers all support the new jQuery.Deferred syntax:
$.read('/tasks/{id}.json', { id: 34 }).then(function (task) { /* do something with task */ });
jQuery.rest will look for a content-type setting in three places:
options.contentTypeif you're using the alternate syntax
$.restSetup.contentType
jsonor
xmlextension on the url resource.
If all three of those sources fail, it will use the browser's default.
There is a global object called $.restSetup that you can modify in your application's Javascript startup to match your environment.
$.restSetup.csrfParamand
$.restSetup.csrfTokendefine how the authenticity token is formatted. By default they are loaded from meta tags named
csrf-paramand
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.methodParamcan 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=
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
(
$.readwill of course always use GET, but the others can be changed to anything you desire.)