• rext
  • Quick Import
  • IE 9- Support
  • API
    • XMLHttpRequest
    • JSONP
    • Promise Object Returned
  • Options
  • Case Matrix
  • Take a Look at headers['Content-Type']
  • Take a Look at responseType
  • License

A light-weight (< 5kb gzipped) and Promise-supported HTTP request library, for all browsers (i.e. even cross-domain requests in IE 6 are possible).

| IE / Edge | Chrome | Firefox | Safari | | :---: | :---: | :---: | :---: | | 6+ ✔ | All ✔ | All ✔ | All ✔ |

Quick Import

npm install --save rexter

var rext = require('rexter');

IE 9- Support

If IE9- browsers are required to send cross-domain requests with user credentials, define the invoker-hostname whitelist in dist/iframe-agent.html and put it at the root path of the target origin.

For example:

Define the invoker-hostname whitelist in iframe-agent.html:

Replace

[/* Define a whitelist of host names here, e.g. '.invoker.com'. */]

with

['.my-domain.com', '.my-domain1.com']

Additianally, before rext is imported, the JSON polyfill (e.g. JSON-js) shall be executed.

⚠️ rext does not include full polyfills in itself.

API

As simple as rext(options).

Besides, the format of jQuery ajax's option object is also allowed:

{
    type: 'post',
    url: '/path/to/api',
    data: {},
    contentType: 'application/json',
    dataType: 'json',
    xhrFields: {
        withCredentials: true
    },
    success: function () { /**/ },
    error: function () { /**/ },
    complete: function () { /**/ }
}

XMLHttpRequest

The success, error, always callbacks are allowed both a chain call and defined in the option object.

rext({
    url: '/path/to/resource',
    data: { /**/ },
    promise: false
}).success((data, response) => {
    /**/
}).error((data, response) => {
    /**/
}).always((data, response) => {
    /**/
});

JSONP

The callback function is allowed either as the second parameter behind the option object or defined in the option object.

rext({
    jsonp: true,
    url: '/path/to/resource',
    data: { /**/ }
}, data => {
    /**/
});

Promise Object Returned

A Promise object is returned by default. Set property promise value false if you do not want to get a Promise object or you prefer to use success and error methods actually.

rext({
    url: '/path/to/resource',
    data: { /**/ }
}).then(data => {
    /**/
}).catch(err => {
    /**/
});

👏 shenfe/promises-aplus is used as a polyfill when the browser does not support Promise.

Options

Instructions of the option object:

| Property | Type | Value | | :---: | :---: | :--- | | type | {Undefined\|String} | 'get' (default), 'post'. | | url | {String} | The resource url string. | | data | {Undefined\|Object} | The data to send. Object recommended. | | withCredentials | {Undefined\|Boolean} | undefined (false, as default), true. The withCredentials property of the request. Whether to send user credentials with the request to another origin or not. An xhrFields object with withCredentials property of value true is accepted as well. | | agent | {Undefined\|Boolean} | undefined (false, as default), true. Whether to fall back to the iframe agent directly when the request is cross-domain and the browser is IE 9-. | | agentPageUrl | {Undefined\|String} | undefined (`${targetOrigin}/iframe-agent.html`, as default), a url string. Specify the url of the iframe agent page if it's not in the root path of the target origin. | | responseType (or dataType) | {Undefined\|String} | 'text' (default), 'json', .etc. Similar to the dataType option in jQuery ajax. A simple trial of JSON parsing would be conducted upon the response data besides the MIME type. See below for more. | | headers | {Undefined\|Object} | The request headers object. Usually used to define the Content-Type property (similar to the contentType option in jQuery ajax), of which 'application/x-www-form-urlencoded' is the default value. See below for more. | | contentType | {Undefined\|String} | The same as headers['Content-Type']. | | jsonp | {Undefined\|Boolean} | undefined (false, as default), true. The same as setting responseType (or dataType) jsonp. | | promise | {Undefined\|Boolean\|Function} | undefined, false, true, or a Promise object constructor. Whether to return a Promise object. Set it false if not for a Promise object. | | simple | {Undefined\|Boolean} | undefined (false, as default), true. Whether not to force an X-Requested-With header in an XHR. |

Case Matrix

All the cases of browser requests.

| Cross-Domain | With-Credentials | Web Browser | Approach | Restriction | Security | | :---: | :---: | :---: | :---: | :--- | :--- | | no | - | IE 6- | ActiveXObject | Almost the same API as the XMLHttpRequest Object. | - | | no | - | IE 7-9 | XMLHttpRequest | The XMLHttpRequest Object. | - | | yes | no | IE 8-9 | XDomainRequest | XDomainRequest - Restrictions, Limitations and Workarounds | - | | no | - | IE 10-11, non-IE | XMLHttpRequest (Level 2) | XMLHttpRequest Level 2. IE 10-11 do not support value json as XHR's responseType, but it doesn't matter. | - | | yes | - | IE 10-11, non-IE | XMLHttpRequest (Level 2) | Server responses should include the Access-Control-Allow-Origin HTTP response header with value *, or the exact origin of the calling page. | - | | yes | yes | IE 10-11, non-IE | XMLHttpRequest (Level 2) | Server responses should include the Access-Control-Allow-Origin HTTP response header with the exact origin of the calling page, and the Access-Control-Allow-Credentials HTTP response header with value true. | - | | - | - | - | JSONP | - | Security concerns | | - | - | - | iframe agent | Be put in a specific place of the target origin. | A whitelist of visitor origins is required. |

Take a Look at headers['Content-Type']

The MIME type of data to send, like the contentType in jQuery ajax.

| Value | Effect | | :---: | :--- | | application/x-www-form-urlencoded | The default, recommended. Almost the same as the url query string. | | multipart/form-data | HTML 4 specification. This allows entire files to be included in the data. Use this when the form includes any <input type="file"> element. | | text/plain | HTML 5 specification. Not recommended. Do not use it unless for debugging. | | application/json | Personally not recommended for common POST requests. Make sure you really need to post complex data with user credentials. Additionally, for CORS requests, setting the content type to anything other than application/x-www-form-urlencoded, multipart/form-data, or text/plain will trigger the browser to send a preflight OPTIONS request to the server. |

Take a Look at responseType

The alias of the expected MIME type of data to receive, similar to the dataType in jQuery ajax. This option should affect the request header Accept and how to treat the response data, relating the response header Content-Type. However, a simple trial of JSON parsing would be conducted then regardless of the type of response data.

According to the specification of responseType, the value can be:

| Value | Description | | :---: | :--- | | text | Default. | | json | - | | blob | If to receive files. | | arraybuffer | If to receive files. | | document | Seldom. |

License

MIT

Copyright (c) 2017-present, shenfe