rest JavaScript API Module

jQuery.telligent.evolution REST helpers

This module exposes helper methods to assist with performing ajax requests against the REST API. They are essentially thin wrappers over jQuery.ajax(), and all options supported by jQuery.ajax() are supported by these wrappers. However, using these wrappers provides the following benefits:

Auth Tokens are automatically pre-set on the requests' headers. Security "just works"
The proper Rest-Method verb overload header is added when it's a PUT or DELETE
Items in the data option are automatically interpolated into the parameterized Endpoint URL as demonstrated below.
REST api endpoints' parameters are automatically uri-encoded
Multiple REST requests can be batched into parallel or sequential unified requests

Methods

get

$.telligent.evolution.get(options)

post

$.telligent.evolution.post(options)

put

$.telligent.evolution.put(options)

del

$.telligent.evolution.del(options)

Options is an optional object which supports all the same parameters defined by jQuery.ajax(). However, there is no need to set auth tokens or Rest-Method overload headers via beforeSend(). Additionally, error handling is provided out of the box via display of a notification containing the error. This can be overridden with the standard error handler parameter.

Additional Supported Options

batch: (number) When provided, defers execution of the request until the associated batch is run
warning: (function(xhr, warningMessage)) When provided, the default warning handler is overridden

batch

$.telligent.evolution.batch(function() {
    // ordinary REST requests
    // $.telligent.evolution.post({...})
    // $.telligent.evolution.get({...})
    // $.telligent.evolution.put({...})
}, options);

High-level syntax wrapper which runs all wrapped REST requests in a single batched HTTP request. Each REST request still supports individual success/error callbacks as well as individual promise callbacks, though these callbacks are not executd until the batch completes. It is not necessary to pass an explicit batch id to REST requests performed within a call to batch(). Bathches created using this method cannot be nested. Returns a promise which resolves when the entire batch completes.

Options is an optional object supporting:

sequential: (bool) When true, performs each batched request in order on the server. When false, runs them in parallel on the server. A sequential batch that contains a failed request will halt all subsequent requests in the batch and reject the entire batch promise. Any successful sub-requests are still resolved. Parallel requests that contain one or more failed requests still resolve the entire batch and do not halt other sub requests.
- default: false
beforeSend: (function) function which accepts an XmlHttpRequest to perform an action before the parent batch's ajax request is performed. Individual beforeSend callbacks on batch sub-requests are not supported.

batch.create

var batchId = $.telligent.evolution.batch.create();

Lower-level method for specifically creating a batch context. Calls to get(), post(), put(), and del() support a batch parameter which defers their execution until the associated batch is run. Batch contexts expire after 60 seconds of not being executed.

It is usually simpler to use the higher-level $.telligent.evolution.batch() method instead, except in cases where it isn't feasible to wrap all REST requests in a single function scope.

batch.process

$.telligent.evolution.batch.process(batchId, options);

Lower-level method which runs a batched REST request with all REST requests associated with that batch ID. Returns a promise which resolves when the entire batch completes.

Options is an optional object supporting:

sequential: (bool) When true, performs each batched request in order on the server. When false, runs them in parallel on the server. A sequential batch that contains a failed request will halt all subsequent requests in the batch and reject the entire batch promise. Any successful sub-requests are still resolved. Parallel requests that contain one or more failed requests still resolve the entire batch and do not halt other sub requests.
- default: false
beforeSend: (function) function which accepts an XmlHttpRequest to perform an action before the parent batch's ajax request is performed. Individual beforeSend callbacks on batch sub-requests are not supported.

It is usually simpler to use the higher-level $.telligent.evolution.batch() method instead, except in cases where it isn't feasible to wrap all REST requests in a single function scope.

Examples

Deleting a user from a group.

Note that the {GroupId} and {UserId} parameters in the URL are left parameterized, and items in data will resolve to the URL before it is requested.

jQuery.telligent.evolution.del({
    url: $.telligent.evolution.site.getBaseUrl() + '/api.ashx/v2/groups/{GroupId}/members/users/{UserId}.json',
    data: {
        GroupId: 5,
        UserId: 2107
    },
    success: function(response) { console.log(response); }
});

Add a message to an existing conversation

Note that in this case, Id gets interpolated into the raw API endpoint as /api.ashx/v2/conversations/50.json, but Subject and Body are still passed as post parameters, and Id is not

jQuery.telligent.evolution.post({
    url: $.telligent.evolution.site.getBaseUrl() + '/api.ashx/v2/conversations/{Id}.json',
    data: {
        Id: 50,
        Subject: "New Mesage Subject",
        Body: "New Message Body"
    },
    success: function(response) { console.log(response); }
});

Request Conversations

This is a more traditional scenario, where PageSize and PageIndex are passed as query string parameters to the URL, which needs no interpolation.

jQuery.telligent.evolution.get({
    url: $.telligent.evolution.site.getBaseUrl() + '/api.ashx/v2/conversations.json',
    data: {
        PageSize: 10,
        PageIndex: 3
    },
    success: function(response) { console.log(response); }
});

Recommended