ti.xhr:

ti.xhr is a wrapper around Titanium's HTTPClient. It works perfectly with REST API endpoints and has a built in cache system that you can use for your requests. But it also can be use for any HTTP requests, you can even cache remote images.

Installation.

Use NPM to install ti.xhr.

Run this command in your lib folder (Alloy) or Resources folder (classic) or in the root directory of your app when using Webpack.

npm i ti.xhr

Usage:

In your alloy.js (or elsewhere), call:

//include ti.xhr
var xhr = new(require("ti.xhr"))();

All methods share the same structure, though with PUT, POST and PATCH require both the url and the data properties. GET and DELETE require just the url property, data is not supported.

// structure for DELETE looks the same as for GET
xhr.GET({
    url: 'http://freegeoip.net/json/',
    onSuccess: onSuccessCallback,
    onError: onErrorCallback,
    extraParams: options
});

xhr.DELETE({});

// structure for PUT and PATCH is the same as for POST
xhr.POST({
    url: 'http://freegeoip.net/json/',
    data: myData,
    onSuccess: onSuccessCallback,
    onError: onErrorCallback,
    extraParams: options
})

xhr.PUT({});
xhr.PATCH({});

Options

In the 5 API call methods you can set options, but doing this every time might be a bit frustrating. Especially if you want authentication for every API call. (or other options). You can set it globally like this

xhr.setStaticOptions(options);

If you do specify options in an API call, it will not ignore global options. This might be useful if all but 1 API call should be authenticated for example.

Available Options

• async (default true) - If an API call should be async or not
• ttl (default false) - Minutes the API response should be cached (only works with GET())
• shouldAuthenticate (default false) - Should the call be made with authentication? BASIC Auth & oAuth supported
• oAuthToken - oAuth token. Only works if shouldAuthenticate is true
• username - Username for BASIC authentication. Only works if shouldAuthenticate is true and oAuthToken is not set
• password - Password for BASIC authentication. See username
• contentType (default application/json)- contentType for API call.
• parseJSON (default false) - Should provided data for POST() and PUT() be stringified and response (for all methods) be parsed.
• returnXML (default false) - Do you expect XML returned, put this to true
• debug (default false) - Do you want Ti.API.info to show API calls made
• requestHeaders (default []) - Add custom request headers to the request
• promise (default false) - Returns a Promise when true

For some examples please check out the examples.js file. Or browse around the ti.xhr.js file. You can find in there support for GET, POST, PUT, PATCH and DELETE

requestHeaders property

To add extra, custom, requestHeaders to the http request, you can set an array like this:

    xhr.setStaticOptions({
        requestHeaders: [
            {
                key: 'myCustomId',
                value: 'myCustomValue'
            }
        ],
        debug: true
    });

This will set the requestHeader like you would do previously:

    xhr.setRequestHeader('myCustomId', 'myCustomValue');

Promises

If you want to use promises you can set the promise property, best would be to use the setStaticOptions method for that so you never have to configure it again.

    xhr.setStaticOptions({
        promise: true
    });

Then every call returns a promise, which you can handle using await or then as with all promises.

    await result = xhr.GET({});

    xhr.GET({}).then(result => {

    });

Promises work with all supported methods. Don't forget to add error handling.

Helpers

Apart from the RESTful way of interacting with your API endpoints, this module also includes the following helper methods:

clear(url)

• url: (required) The URL you want removed from the cache manager

Finds the cached document of the given url (if any) and removes it from the cache manager. This method is useful if you are not satisfied with the results you got at the time.

clean()

Goes through all the cached documents and delete everything that has been expired (if their TTL timestamp is less than the current time)

This method returns the count of deleted documents

purge()

Goes through all the documents and deletes everything

This method returns the count of deleted documents

Backwards Compatibility

Previously get, post, put and destroy methods were used. They were deprecated in version 2, and removed in version 3.

About:

Created by Rene Pot, @Wraldpyk

Contributions by:

• Original creator: Raul Riera, @raulriera

• Daniel Tamas, @dan_tamas

• Bob Sims, @2wheelsburning

• Mark Ross @rossman66