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, raw. Use raw 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 I interface and new improvements to REST JS.
To support backwards-compatibility, request() will automatically conform legacy-shaped I to the updated v5 interface and emit a warning to the user when they pass deprecated request options into request().
raw Request()
REST JS v5 introduces raw 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.
I Request Options
I now has five top level parameters in REST JS v5:
authenticationparamsportalfetchOptions requestFlags
All other top-level properties of I have been deprecated or removed. The details and migration instructions for those are listed below in the breaking changes section and the migration guide.
fetch Options
In REST JS v4, HTTP fetch options such as http, headers, signal, etc., existed as standalone I properties.
In REST JS v5, HTTP fetch options are grouped under a fetch object matching the Fetch API's Request object, allowing users to pass fetch options around together as needed across requests.
request Flags
For options specific to the request() method, REST JS v5 introduces a new I interface. Here is where you can set v5 flags that define request behavior:
suppressWarnings useAuthorization Header useX Esri Authorization Header ignoreMax Url Length
These flags existed in previous versions as standalone top-level I properties. In REST JS v5, they have been updated and grouped together.
process Options()
REST JS v5 features a new utility method process to handle large options objects. It allows users to parse large options objects into a v5-compatible I object with correctly shaped params.
Users can use this method to:
- simplify large request options objects
- send properties to the request
paramsobject - extract properties for further use
- set default
IpropertiesRequest Options - return an
Iobject that is compatible with v5Request Options request().
request()
REST JS v5 brings generic types to request. Users can now declare return types to request 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 I 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 raw.
Removed raw Response
REST JS v5 no longer supports raw. Users will no longer be able to fetch an HTTP Response object by supplying a raw property to request() via the I parameter. Fetching a native response object is now handled by a new method, raw.
Users who were using raw with request() will need to migrate to use raw to fetch an HTTP response.
Removed from I Request Options
raw has been removed from the I interface and is no longer supported.
Removed from REST JS packages
As part of removing raw, the REST JS methods below no longer support raw in request options in REST JS v5.
geocode()bulkGeocode() getItem Data() getFeature() queryFeatures()
These methods now implement raw, 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 with Options()
REST JS v5 removes with as it seemed to have limited use. Going forward, the standard practice to make requests with options is to define properties on an I object, then pass that to request().
const wrappedRequest = withOptions({
authentication: session
}, request);
wrappedRequest(url);
const options = {
authentication: session
}
request(url, options);Removed request from I Request Options
In v4, request existed on I to support a legacy testing framework which has been replaced. In REST JS v5, the request property has been removed from I 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 I 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 I, 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.
append Custom Params() method
The append method is deprecated and has been replaced with process 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 raw Response to raw Request()
The following code examples cover basic and special cases for using request() in v4 that now require raw in REST JS v5.
Fetch an HTTP response object with raw Request()
In REST JS v5, use raw to access HTTP response object.
let options = {
rawResponse: true
}
let response = await request(url, options);
let response = await rawRequest(url);Fetch response as a non-JSON format with raw Request()
In v4, certain response formats such as text could be requested without raw. In REST JS v5, use raw to query response types other than json.
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 v5Query service as pbf with raw Request()
In v4, users could supply a request with raw for pbf queries. In REST JS v5, use raw to query pbf feature data.
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 fetch Options
In v4, HTTP fetch options including http were located in the top level of I.
let requestOptions = {
params: { ... },
httpMethod: "POST",
credentials: "omit",
portal: "https://domain.com/portal-url"
}In REST JS v5, http has been renamed to method and all HTTP-related fetch options should be moved into fetch.
let requestOptions = {
params: { ... },
portal: "https://domain.com/portal-url",
fetchOptions: {
method: "POST",
credentials: "omit"
}
}Migrate to request Flags
To migrate to v5, use the new request object property of I to set REST JS-specific request flags.
In v4, request settings were located in the top level of I.
let requestOptions = {
suppressWarnings: true,
maxUrlLength: 67,
hideToken: true
}In REST JS v5, move all request settings into the request object, update max to the v5 version as shown here, and update hide according to the migration instructions here.
let requestOptions = {
requestFlags: {
suppressWarnings: true,
ignoreMaxUrlLength: true,
useAuthorizationHeader: true,
useXEsriAuthorizationHeader: true
}
}Migrate max Url Length to ignore Max Url Length
Before v5, a user could specify a max, beyond which a GET request would switch to POST if the total URL length exceeded the max.
Now, request will always convert GET requests to POST if the url length exceeds 2000, unless the user chooses to ignore it by setting ignore. 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 ignore in request flags.
// 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 ignoreMaxUrlLengthREST 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.
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 hide Token to authorization headers
In v4, a user could provide hide 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, hide 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, use and use. 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 hide to use the use and use request flags instead:
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 raw Request() 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:
getItem Data Raw() queryFeatures Raw()
To migrate:
Use get instead of get, and remove raw from the request options.
Use query instead of query, and remove raw 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.