types | References | ArcGIS Maps SDK for JavaScript

Types

import type { RequestOptions, ResponseType, RequestResponse, GetAllHeaders, GetHeader } from "@arcgis/core/request/types.js";

Type definitions

RequestOptions

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

An object with the following properties that describe the request.

Supertypes: AbortOptions

authMode

Property

Type: "anonymous" | "auto" | "immediate" | "no-prompt" | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates if and how requests to ArcGIS Services are authenticated. Only applicable when esriConfig.request.useIdentity = true.

Known Value	Description
auto	The user will be signed in when a secure resource is requested.
anonymous	An error will be returned when a secure resource is requested.
immediate	The user will be signed in before the resource is requested.
no-prompt	Checks for whether the user is already signed in. If so, no additional prompts display for sign-in.

Note: This is not supported when used in a custom worker that is not using the workers framework.

Default value: auto

body

Property

Type: FormData | HTMLFormElement | string | null | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

If uploading a file, specify the form data or element used to submit the file here. If specified, the parameters of the query will be added to the URL.

cacheBust

Property

Type: boolean | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

If true, the browser will send a request to the server instead of using the browser's local cache. If false, the browser's default cache handling will be used.

Default value: false

headers

Property

Type: Record<string, string> | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Headers to use for the request. This is an object whose property names are header names.

keepAlive

Property

Type: boolean | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether the browser will keep the associated request alive if the page that initiated it is unloaded before the request is complete, such as during page navigation or closing. See also keepalive for more details.

Default value: false

method

Property

Type: "auto" | "delete" | "head" | "post" | "put" | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates if the request should be made using the HTTP DELETE, HEAD, POST, or PUT method. By default, HTTP POST will be used for auto if the request size is longer than the maxUrlLength property set in Config.

Default value: auto

responseType

Property

Type: ResponseType | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Response format. For details on the specific types, see: json, text, array-buffer, blob, image, native, native-request-init, document, and xml

Default value: json

timeout

Property

Type: number | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates the amount of time in milliseconds to wait for a response from the server. Set to 0 to wait for the response indefinitely.

Default value: 62000

useProxy

Property

Type: boolean | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates the request should use the proxy. By default, this is determined automatically based on the domain of the request URL.

Default value: false

withCredentials

Property

Type: boolean | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates if cross-site Access-Control requests should use credentials. It is also possible to push the domain to the config trustedServers if an application requires credentials. For additional information on withCredentials, please refer to this documentation.

Default value: false

query

Property

Type: Record<string, any> | URLSearchParams | null | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Query parameters for the request.

The query parameters will be added to the URL if a GET request is used, or if the body property is set. If the body property is not set, the query parameters will be added to the request body when a DELETE, POST, or PUT request is used.

ResponseType

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

Type: "array-buffer" | "blob" | "document" | "image" | "json" | "native" | "native-request-init" | "text" | "xml"

RequestResponse

Type definition

Type parameters: <T>

Since: ArcGIS Maps SDK for JavaScript 5.0

Returns a promise that resolves to an object with the following specification. If the request returns an Error, the error object will include the details specified in RequestErrorDetails.

data

Property

Type: T

Since: ArcGIS Maps SDK for JavaScript 5.0

The requested data. This value should match the RequestOptions responseType with the data return type. Possible types are: json, text, array-buffer, blob, image, native, native-request-init, document, and xml.

getAllHeaders

Property

Type: GetAllHeaders | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Method for getting all headers sent from the server.

getHeader

Property

Type: GetHeader | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Method for getting a header sent from the server.

httpStatus

Property

Type: number | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

The status code of the http response.

requestOptions

Property

Type: RequestOptions | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

The options specified by the user in the data request. See RequestOptions for available properties.

ssl

Property

Type: boolean | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates if the request required https.

url

Property

Type: string | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

The URL used to request the data.

Example

// request GeoJson data from USGS remote server
let url = "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson";

esriRequest(url, {
  responseType: "json"
}).then((response) => {
  // The requested data
  let geoJson = response.data;
});

GetAllHeaders

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

A function to retrieve all headers sent from the server. CORS only allows a few response headers to be read by default, see: Access-Control-Expose-Headers.

Returns: [ string, string ][] | null | undefined
An array of all headers returned from the server. Each header is an array containing the header name and its corresponding value.

Example

esriRequest(url, options)
  .then((response) => {
    console.log("All request headers: ", response.getAllHeaders());
  });

GetHeader

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

A function to retrieve headers sent from the server. CORS only allows a few response headers to be read by default, see: Access-Control-Expose-Headers.

Parameters

Parameter	Type	Description	Required
headerName	string	The name of the header.

Returns: string | null | undefined
The header value.

Example

esriRequest(url, options)
  .then((response) => {
    // prints the content type of the request: 'application/json'
    console.log("header: ", response.getHeader('Content-Type'));
  });

RequestErrorDetails

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

The specification of the details object returned in an Error object.

url

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 5.0

The URL of the request that returned an error message.

requestOptions

Property

Type: RequestOptions

Since: ArcGIS Maps SDK for JavaScript 5.0

The options used in the http request.

getAllHeaders

Property

Type: GetAllHeaders

Since: ArcGIS Maps SDK for JavaScript 5.0

A function for retrieving all headers sent from the server.

getHeader

Property

Type: GetHeader

Since: ArcGIS Maps SDK for JavaScript 5.0

A function to retrieve headers sent from the server.

httpStatus

Property

Type: number

Since: ArcGIS Maps SDK for JavaScript 5.0

The status code of the http response.

raw

Property

Type: string | Object

Since: ArcGIS Maps SDK for JavaScript 5.0

The raw error object if the server returned a JSON error, or the response text otherwise.

subCode

Property

Type: number

Since: ArcGIS Maps SDK for JavaScript 5.0

The error message subcode.

messageCode

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 5.0

The error message code.

messages

Property

Type: string[]

Since: ArcGIS Maps SDK for JavaScript 5.0

Additional error message(s).

ssl

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates if the request required https.

RequestParameters

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

requestOptions

Property

Type: RequestOptions

Since: ArcGIS Maps SDK for JavaScript 5.0

The options specified by the user in the data request. See RequestOptions for available properties.

url

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 5.0

The request URL.

RequestInterceptor

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

Specifies the object used for intercepting and modifying requests made via esriRequest.

after

Property

Type: AfterInterceptorCallback | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Makes changes to the response after the request is sent, but before it's returned to the caller.

before

Property

Type: BeforeInterceptorCallback | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Make changes to the request URL or options before the request is sent. A returned value will be used as the response data, which would prevent the request from being sent.

error

Property

Type: ErrorInterceptorCallback | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

When an error occurs during the request processing, this function is called with an Error object giving the details about what happened. For example, this could be used to log specific errors occurring with layers or services.

headers

Property

Type: Record<string, string> | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Sets or adds headers into requestOptions.headers. See also: RequestOptions.

query

Property

Type: Object | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Sets or adds query parameters into requestOptions.query. See also: RequestOptions.

responseData

Property

Type: any | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Hardcodes the response. The request will not be sent. This is resolved as the response data.

urls

Property

Type: RegExp | string | Array<RegExp | string> | undefined

Since: ArcGIS Maps SDK for JavaScript 5.0

Specifies the URL(s) to apply to the interceptors. If the value is type String, then it matches if the request URL starts with that string. If null or undefined, the interceptor will apply to all relevant requests. If using a RegExp, the g and y flags should not be used.

Examples

const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the BeforeInterceptorCallback to check if the query of the
  // FeatureLayer has a maxAllowableOffset property set.
  // if so, then set the maxAllowableOffset to 0
  before: function(params) {
    if (params.requestOptions.query.maxAllowableOffset) {
      params.requestOptions.query.maxAllowableOffset = 0;
    }
  },
  // use the AfterInterceptorCallback to check if `ssl` is set to 'true'
  // on the response to the request, if it's set to 'false', change
  // the value to 'true' before returning the response
  after: function(response) {
    if (!response.ssl) {
      response.ssl = true;
    }
  }
});

const featureLayer = new FeatureLayer({
   url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/3"
});

esriConfig.request.interceptors.push({
   urls: featureLayer.url,
   // set the error function and check if an error occurs, and if it's name is "AbortError"
   // if so, display a useful error about the layer, if not, ignore the error
   error: function(error) {
      if (error.name == "AbortError") {
         // we're only interested in aborted request errors
         console.error(`An error happened with layer ${featureLayer.title}`, error);
      }
      return;
   }
});

AfterInterceptorCallback

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

Makes changes to the response after the request is sent, but before it's returned to the caller.

Parameters

Parameter	Type	Description	Required
response	RequestResponse<any>	The response object.

Returns: void

Example

const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the AfterInterceptorCallback to check if `ssl` is set to 'true'
  // on the response to the request, if it's set to 'false', change
  // the value to 'true' before returning the response
  after: function(response) {
    if (!response.ssl) {
      response.ssl = true;
    }
  }
});

BeforeInterceptorCallback

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

Makes changes to the request URL or options before the request is sent. A returned value will be used as the response data, which would prevent the request from being sent.

If null or undefined is returned, the request is sent with whatever changes were made to the parameters. If an Error is returned, the request is rejected with an esriError. If any other type is returned, the request is resolved with the returned value as the response data (request will not be sent).

Parameters

Parameter	Type	Description	Required
params	RequestParameters	Parameters object that specifies the two properties that can be set.

Returns: any
Returns: null, undefined, Error, response data, or a Promise that resolves to any one of these object types.

Examples

// modifying the query parameters
const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the BeforeInterceptorCallback to check if the query of the
  // FeatureLayer has a maxAllowableOffset property set.
  // if so, then set the maxAllowableOffset to 0
  before: function(params) {
    if (params.requestOptions.query.maxAllowableOffset) {
      params.requestOptions.query.maxAllowableOffset = 0;
    }
  }
});

// fetching the data in place of the requests
const wmsLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/services/911CallsHotspot/MapServer/WMSServer";

esriConfig.request.interceptors.push({
   urls: wmsLayerUrl,
   before: function(params) {
     if (params.url === url && params.requestOptions.responseType === "xml") {
        if ("fetch" in window && "TextDecoder" in window) {
           // decode the response as ISO-8859-1 if it's not UTF-8 as expected
           return fetch(url + "?SERVICE=WMS&REQUEST=GetCapabilities")
             .then(function(response) {
               return response.arrayBuffer();
             })
             .then(function(buffer) {
               let textDecoder = new TextDecoder("ISO-8859-1"); // specified in the Capabilities XML declaration
               let xmlText = textDecoder.decode(buffer);
               let parser = new DOMParser();
               xml = parser.parseFromString(xmlText, "application/xml");
               return xml;
             });
         }
     }
   }
});

ErrorInterceptorCallback

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.0

The error function detailing the reason why the request failed.

Parameters

Parameter	Type	Description	Required
error	Error<unknown>	The error object. See Error for more information.

Returns: void