Overview

ArcGIS REST JS v5 brings a standard JSON response to request() and changes the way users fetch an HTTP Response object.

Support for fetching an HTTP Response object has moved to a new method, rawRequest(). Use rawRequest() when you need access to the response object, when you need to request with custom format params, or when you need fine-tuned control over the response data, such as streaming or requesting pbf data.

REST JS v5 features significant changes to the IRequestOptions interface and new improvements to REST JS. To support backwards-compatibility, request() will automatically conform legacy-shaped IRequestOptions to the updated v5 interface and emit a warning to the user when they pass deprecated request options into request().

rawRequest()

REST JS v5 introduces rawRequest() as the standard method for fetching a native HTTP Response object. Any methods that require an HTTP response should call this method, and then process the response as desired.

IRequestOptions

IRequestOptions now has five top level parameters in REST JS v5:

All other top-level properties of IRequestOptions have been deprecated or removed. The details and migration instructions for those are listed below in the breaking changes section and the migration guide.

fetchOptions

In REST JS v4, HTTP fetch options such as httpMethod, headers, signal, etc., existed as standalone IRequestOptions properties.

In REST JS v5, HTTP fetch options are grouped under a fetchOptions object matching the Fetch API's RequestInit object, allowing users to pass fetch options around together as needed across requests.

requestFlags

For options specific to the request() method, REST JS v5 introduces a new IRequestFlags interface. Here is where you can set v5 flags that define request behavior:

These flags existed in previous versions as standalone top-level IRequestOptions properties. In REST JS v5, they have been updated and grouped together.

processOptions()

REST JS v5 features a new utility method processOptions() to handle large options objects. It allows users to parse large options objects into a v5-compatible IRequestOptions object with correctly shaped params.

Users can use this method to:

  • simplify large request options objects
  • send properties to the request params object
  • extract properties for further use
  • set default IRequestOptions properties
  • return an IRequestOptions object that is compatible with v5 request().

request()

REST JS v5 brings generic types to request. Users can now declare return types to request<T>() to specify a return data type. request() will also try to infer return types by default.

Breaking changes

Four top-level properties have been removed from IRequestOptions without backwards-compatible support in REST JS v5. Refer to the corresponding sections in the migration guide to migrate these properties to updated behavior.

Removed special return types from request()

request() now returns only JSON, and recognizes only json or geojson format params. request() will no longer process f params that result in non-JSON responses, such as text. Instead, it will convert the request format to json in those cases.

To request a response type other than JSON, users must use rawRequest().

Removed rawResponse

REST JS v5 no longer supports rawResponse. Users will no longer be able to fetch an HTTP Response object by supplying a rawResponse property to request() via the IRequestOptions parameter. Fetching a native response object is now handled by a new method, rawRequest().

Users who were using rawResponse with request() will need to migrate to use rawRequest() to fetch an HTTP response.

Removed from IRequestOptions

rawResponse has been removed from the IRequestOptions interface and is no longer supported.

Removed from REST JS packages

As part of removing rawResponse, the REST JS methods below no longer support rawResponse in request options in REST JS v5.

  • geocode()
  • bulkGeocode()
  • getItemData()
  • getFeature()
  • queryFeatures()

These methods now implement rawRequest(), or have dropped support altogether. Support for returning a Response object has been moved to new methods. See the instructions in the migration guide for how to fetch an HTTP response object using new response access methods.

Removed withOptions()

REST JS v5 removes withOptions() as it seemed to have limited use. Going forward, the standard practice to make requests with options is to define properties on an IRequestOptions object, then pass that to request().

Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
const wrappedRequest = withOptions({
  authentication: session
}, request);

wrappedRequest(url);

const options = {
  authentication: session
}

request(url, options);

Removed request from IRequestOptions

In v4, request existed on IRequestOptions to support a legacy testing framework which has been replaced. In REST JS v5, the request property has been removed from IRequestOptions as it was not intended for any consumer use and should be removed.

Removed compatibility packages

arcgis-rest-form-data and arcgis-rest-fetch compatibility packages have been removed, as REST JS v5 now uses native WebAPI fetch. This change shouldn't affect most users but is included here so users can be aware of the change.

Removed support for Node.js 18, 20

REST JS v5 drops support for Node.js 18 and 20, and has been updated to support Node.js 22 and later.

Deprecations

The following properties of IRequestOptions have been deprecated, but are backwards-compatible with version 4. Click each property to navigate to its migration section.

These following properties are also deprecated on IRequestOptions, but their implementations have been removed from REST JS. Users must migrate to the new behavior in REST JS v5. Click each property to navigate to its migration section.

appendCustomParams() method

The appendCustomParams() method is deprecated and has been replaced with processOptions() in REST JS v5.

Migration guide

To migrate REST JS from version 4.0 to version 5.0, refer to the instructions in each section below.

Migrate rawResponse to rawRequest()

The following code examples cover basic and special cases for using request() in v4 that now require rawRequest() in REST JS v5.

Fetch an HTTP response object with rawRequest()

In REST JS v5, use rawRequest() to access HTTP response object.

Use dark colors for code blocks
1
2
3
4
5
6
let options = {
  rawResponse: true
}
let response = await request(url, options);

let response = await rawRequest(url);

Fetch response as a non-JSON format with rawRequest()

In v4, certain response formats such as text could be requested without rawResponse. In REST JS v5, use rawRequest() to query response types other than json.

Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
let options = {
  params: {
    f: "text"
  }
}

let text = await request(url, options); // returned response.text(), or response.blob() for unrecognized format.

let response = await rawRequest(url);
response.text(); // user manually handles format in v5

Query service as pbf with rawRequest()

In v4, users could supply a request with rawResponse for pbf queries. In REST JS v5, use rawRequest() to query pbf feature data.

Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let options = {
  rawResponse: true,
  params: {
    f: "pbf"
  }
}
let response = await request(url, options);
response.arrayBuffer();

let options = {
  params: {
    f: "pbf"
  }
}
let response = await rawRequest(url, options);
response.arrayBuffer();

Migrate to fetchOptions

In v4, HTTP fetch options including httpMethod were located in the top level of IRequestOptions.

Use dark colors for code blocksCopy
1
2
3
4
5
6
let requestOptions = {
  params: { ... },
  httpMethod: "POST",
  credentials: "omit",
  portal: "https://domain.com/portal-url"
}

In REST JS v5, httpMethod has been renamed to method and all HTTP-related fetch options should be moved into fetchOptions.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
let requestOptions = {
  params: { ... },
  portal: "https://domain.com/portal-url",
  fetchOptions: {
    method: "POST",
    credentials: "omit"
  }
}

Migrate to requestFlags

To migrate to v5, use the new requestFlags object property of IRequestOptions to set REST JS-specific request flags.

In v4, request settings were located in the top level of IRequestOptions.

Use dark colors for code blocksCopy
1
2
3
4
5
let requestOptions = {
  suppressWarnings: true,
  maxUrlLength: 67,
  hideToken: true
}

In REST JS v5, move all request settings into the requestFlags object, update maxUrlLength to the v5 version as shown here, and update hideToken according to the migration instructions here.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
let requestOptions = {
  requestFlags: {
    suppressWarnings: true,
    ignoreMaxUrlLength: true,
    useAuthorizationHeader: true,
    useXEsriAuthorizationHeader: true
  }
}

Migrate maxUrlLength to ignoreMaxUrlLength

Before v5, a user could specify a maxUrlLength, beyond which a GET request would switch to POST if the total URL length exceeded the maxUrlLength. Now, request will always convert GET requests to POST if the url length exceeds 2000, unless the user chooses to ignore it by setting ignoreMaxUrlLength. In that case, the user should provide the desired HTTP method. See below for how to handle both cases.

To force a long URL GET request, set ignoreMaxUrlLength in request flags.

Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// where default max url length is 2000, this request would switch to POST unless configured as follows
const url = STR_LEN_3000;
let options = {
  httpMethod: "GET",
  maxUrlLength: 3000
};
request(url, options); // request stays GET since user specified maxUrlLength >= url.length

let options = {
  fetchOptions: {
    method: "GET"
  },
  requestFlags: {
    ignoreMaxUrlLength: true
  }
}
request(url, options); // request stays GET since user specified ignoreMaxUrlLength

REST JS v5 enforces an implicit max url length of 2000 for requests. To enforce a smaller url max length than 2000, wrap request() with a custom method and add url length checks, then specify the HTTP method accordingly. Below is an example of a service wrapper that safely manages the HTTP method to query services that accept a very small example max url length.

Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
let options = {
  maxUrlLength: 50
};

request(url, options);

function tinyUrlRequest (url, options, maxLength = 50) => {
  const encodedUrl = buildEncodedUrl(...); // your own url string encoderhelper
  const httpMethod = encodedUrl.length > maxLength ? "POST" : "GET";

  let options = {
    fetchOptions: {
      method: httpMethod
    }
  }
  return request(url, options);
}

tinyUrlRequest(url, options);

Migrate hideToken to authorization headers

In v4, a user could provide hideToken in the request options to move the authentication token from the encoded url string to the headers in GET requests, or to the request body in POST requests. In v5, hideToken is deprecated in favor of explicit settings using the request flags.

In REST JS v5, a token that exists in the request params will always be sent in the url of GET requests, and the body of POST requests, unless the user assigns the token to the Authorization headers using the new request flags, useAuthorizationHeader and useXEsriAuthorizationHeader. If the user sets either of those request flags, the token will be moved out of params into the corresponding request headers, regardless of the request method. If a user assigns the token to the request headers manually, any token in the params will be passed to the service in the GET url or POST body, in addition to what was manually assigned in the headers.

Migrate from using hideToken to use the useAuthorizationHeader and useXEsriAuthorizationHeader request flags instead:

Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
let options = {
  httpMethod: "GET" | "POST",
  hideToken: true,
  params: {
    token: "token"
  }
};
request(url, options);

let options = {
  fetchOptions: {
    method: "GET" | "POST"
  },
  requestFlags: {
    useAuthorizationHeader: true
  },
  params: {
    token: "token"
  }
}
request(url, options)

Migrate to rawRequest() HTTP access methods

For methods that still needed to access the HTTP response, REST JS v5 now provides a raw request version of the method:

  • getItemDataRaw()
  • queryFeaturesRaw()

To migrate:

Use getItemDataRaw() instead of getItemData(), and remove rawResponse from the request options.

Use queryFeaturesRaw() instead of queryFeatures(), and remove rawResponse from the request options.

Feel free to create an issue to request official support for other methods that should support fetching a native Response object.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.