Upgrade from v3 to v4

The v4.0.0 release of ArcGIS REST JS centers around 5 major themes:

• Updating supported platforms
• Streamlining packages
• Improving developer UX
• Improving authentication
• Reducing maintenance overhead

Updating supported platforms

ArcGIS REST JS now supports browsers that support fetch and ES 2017 as well as Node JS 12.2. Previous versions of ArcGIS REST JS supported browsers back to IE 11 with fetch and Promise polyfills and any version of Node JS. This is no longer the case. See system requirements for more information.

Streamlining packages

Several similar packages have been consolidated reducing the overall number of packages. This reduces maintenance but also groups similar functionality together to remain consistent.

• @esri/arcgis-rest-auth has been combined into @esri/arcgis-rest-request. The request and authentication packages were often used together and shared many common concepts and dependencies. **Many common exports from @esri/arcgis-rest-auth have also been renamed. See Improve authentication handling for more information.
• @esri/arcgis-rest-feature-service has been renamed into @esri/arcgis-rest-feature-service.
• @esri/arcgis-rest-service-admin has been combined into @esri/arcgis-rest-feature-service.
• @esri/arcgis-rest-types has been deprecated. This library was viewed by many as an authoitative type library for the ArcGIS REST APIs when it was a simple utility library of types that were shared by ArcGIS REST JS methods. See this issue comment for more reasons on this change. Types are now defined directly in the packages where they are used.

Improving developer UX

ArcGIS REST JS v4 adds several key features for improving the overall developer experience.

• ArcGIS REST JS is now distributed as ES modules and aligns with the latest Node JS and bundler standards for determining the module system and package entry points.
• Node JS users are now no longer required to include fetch and form-data polyfills. These are automatically included and used by ArcGIS REST JS.
• Full support for using ArcGIS REST JS as ES modules in Node JS.
• Full support for using ArcGIS REST JS as ES modules in browsers via import maps or the Esm.run CDN

Improving authentication

Renamed classes

The main authentication classes (UserSession, ArcGISIdentityManager and ApiKey) have been renamed. They are now ArcGISIdentityManager, ApplicationCredentialsManager and ApiKeyManager. Their new names better reflect their capabilities as "managing" a token for use in different requests and aligns with the new terminology in the security and authentication chapter.

Also, the functionality in the generateToken function has been moved to the ArcGISIdentityManager class, in the signIn() function.

1
2
3
4
5
6
7
8
9
10
11
import { UserSession } from "@esri/arcgis-rest-auth";
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";

import { ApplicationSession } from "@esri/arcgis-rest-auth";
import { ApplicationCredentialsManager } from "@esri/arcgis-rest-request";

import { ApiKey } from "@esri/arcgis-rest-auth";
import { ApiKeyManager } from "@esri/arcgis-rest-request";

import { generateToken } from "@esri/arcgis-rest-auth";
import { ArcGISIdentityManager } from "@esri/arcgis-rest-request"; // use ArcGISIdentityManager.signIn()

New static methods

In ArcGIS REST JS v4.0.0+, instances of the authentication manager classes (ArcGISIdentityManager, ApplicationCredentialsManager and ApiKeyManager) should all be created with static methods on the class itself. Several new static methods have been added to facilitate this including:

• ArcGISIdentityManager.signIn() - for creating an ArcGISIdentityManager instance from a username and password.
• ArcGISIdentityManager.fromToken() - for creating an ArcGISIdentityManager from an existing token.
• ApplicationCredentialsManager.fromCredentials() - for creating an ApplicationCredentialsManager instance from a client id and client secret.
• ApiKeyManager.fromKey() - for creating an API key manager from an API key.

Direct token usage

It is also now possible to pass an existing token directly to the authentication method. This is an acceptable method for API keys. However, tokens for users/ArcGIS identities should use the new ArcGISIdentityManager.fromToken() method.

1
2
3
4
5
6
7
8
9
10
import { solveRoute } from "@esri/arcgis-request-routing";

solveRoute({
  stops: [
    [-117.195677, 34.056383],
    [-117.918976, 33.812092],
   ],
   authentication: "YOUR_ACCESS_TOKEN"
})
  .then(response)

PKCE support

ArcGISIdentityManager now supports PKCE (Proof Key for Code Exchange) when performing browser based OAuth. This allows for refresh tokens on the client without the need for a server. This is the new default behavior for ArcGISIdentityManager.beginOAuth2() and ArcGISIdentityManager.completeOAuth2(). Tokens will now be short lived and refreshed automatically when they expire. Refresh tokens will also be refreshed when they are about to expire.

You can also manually refresh a token using the new ArcGISIdentityManager.refreshCredentials() method. Refresh tokens can be refreshed with the new ArcGISIdentityManager.exchangeRefreshToken() method.

Signing out

Tokens in an ArcGISIdentityManager can now be expired with the new ArcGISIdentityManager.destroy() static method or ArcGISIdentityManager.signOut() instance method.

Reducing maintenance overhead

ArcGIS REST JS is now automatically released with semantic-release. This means that starting at 4.0.0 packages will only be released when they have changes. This means that some packages will have higher version numbers then other packages but that all packages in the 4.x.x version range are compatible with each other. This will reduce the maintenance overhead of a new release and allow new features to be released faster.