apprt-request

The apprt-request bundle provides an API to perform asynchronous requests.

Usage

The apprt-request bundle implements the interface described by dojo/request.

The apprt-request API provides a set of different methods. If no HTTP method is specified the bundle uses GET by default.

The behavior of apprt-request follows the changes made for esri/request in the ArcGIS Maps SDK for JavaScript 4.9.

Any server is assumed to be CORS-enabled by default.
If it is detected that a server is not supporting CORS, the request is routed over the configured proxy.
A proxy rule can be configured for direct use of a proxy.

API Methods

The interface of apprt-request is described as ConfigurableRequestFunction. For more details consider the API Documentation.

import request from "apprt-request";

// get-request without options parameter
request(url);

// get-request with options parameter
request(url, options);

// explicit get-request (similar to unspecified function call)
request.get(url, options);

// post-request with options parameter
request.post(url, options);

// put-request with options parameter
request.put(url, options);

// delete-request with options parameter
request.del(url, options);

Request arguments

To send a request, the url property is mandatory. However, all option arguments are optional and default values are applied. The request function call returns a promise that contains the data of the response if appropriate.

Property	Type	Default	Description
data	String \| Object	null	Data, if any, that should be sent in the HTTP body with the request. Can only be used with POST, PUT and DELETE.
query	String \| Object	null	The query string, if any, that should be sent with the request.
method	String	GET	The HTTP method that should be used to send the request. Same as using specific function call (`request.get(url, options)`).
timeout	Integer	60000	The number of milliseconds to wait for the response. If this time passes the request is cancelled and the promise rejected.
handleAs	String	based on URL ending	The content handler to process the response payload with. If not defined, the URL ending is used. If it cannot be detected, `json` is the default.
headers	Object		A hash of the custom headers to be sent with the request. Example: `{ 'Content-Type': 'application/x-www-form-urlencoded' }`
useProxy	Boolean	true	If `false` no proxy is applied. If set to `"force"`, all requests use the default proxyUrl if no other rule matches.
jsonp	String	null	The name of the query parameter the server expects the name of the callback function to appear in.
preventCache	Boolean	false	If `true`, sends an extra query parameter to ensure the browser and the server do not supply cached values.
withCredentials	Boolean	false	If `true` allows the browser’s XMLHttpRequest to send credentials or cookies with your cross-domain request.
signal	AbortSignal	null	A signal which allows to abort the request.

Use Cases

How are security tokens added to requests

The bundles apprt-esri-init and apprt-tokens automatically register integration points, which check if a request needs to be enhanced by available security information, e.g. tokens.

How to abort a request

Since version 4.12.0 the AbortController specification is supported by 'apprt-request'.

const aborter = new AbortController();
const url = "http://..."

request(url, {signal: aborter.signal })
    .then((result)=>{
        // not aborted
    },(e)=>{
        if(e.name === "AbortError"){
            // request is cancelled
        }
    })

// abort the request
aborter.abort();

How to modify request default values

The following properties can be overridden:

maxUrlLength
timeout
proxyUrl

Sample for setting properties with set(name, value) - where name is a string and value is a string, boolean, or integer:

request.config.set("maxUrlLength", 1024);

Sample for getting properties:

request.config.get("proxyUrl");

How to modify the request proxy rule

There can only be one proxy rule for a domain. By registering a new proxy rule, an existing rule for the same domain is removed. If no proxy URL is defined the default proxy URL is applied.

Sample for adding a proxy rule:

request.config.addProxyRule({
    origin: "test.de",
    proxyUrl: "http://proxy.de"
});

Sample for removing the proxy rule - removes the proxy rule for matching domain:

request.config.removeProxyRule({
    origin: "test.de"
});

How to modify the trusted servers (CORS with credentials)

By default, login information (authorization information or cookies) that is already present in the browser is not transmitted to CORS-enabled servers. For further information about this topic, see here. By adding a server to the list of trusted servers, the withCredentials flag is enabled for each request to that server.

Sample for adding a trusted server:

request.config.addTrustedServer({
    origin: "test.de"
});

Sample for removing a CORS-enabled server that has a matching domain:

request.config.removeTrustedServer({
    origin: "test.de"
});

How to reset a request configuration to defaults

The following code removes all custom configuration parameters. Instead, defaults apply:

request.config.reset();

How to get a proxied URL from the request

The following code appends and returns a proxied URL based on the configured proxy rules. It does not use a proxy if none of the rules match.

request.getProxiedUrl(url);

Use the optional parameter { force: true } to use the default proxyUrl even when no proxy is configured for the given url's host:

request.getProxiedUrl(url, { force: true });