Upgrade from v2 to v3

Our family of users and contributors has grown (a lot!) since our first release so we decided to roll up our sleeves (groan) and overhaul the API. Our goals were to:

  1. Make ArcGIS REST JS as consistent (and simple) as possible
  2. Introduce building blocks for compositional/fluent APIs
  3. Provide a few new options to reuse common parameters

Fluent APIs

In v2.0.0 we introduced a new class called SearchQueryBuilder to help compose complex parameters.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { searchItems, SearchQueryBuilder } from "@esri/arcgis-rest-portal";

const q = new SearchQueryBuilder()
  .match("Trees")
  .and()
  .match("US Forest Service")
  .in("owner")
  .and()
  .startGroup()
   .match("Web Mapping Application")
   .in("type")
   .or()
   .match("Mobile Application")
   .in("type")
 .endGroup()

// "Trees AND owner: US Forest Service AND (type: "Web Mapping Application" OR type: "Mobile Application")"
searchItems({ q })

Currently only searchItems() and searchGroups() accept SearchQueryBuilder as an input, but we've included building blocks (groan) to create additional implementations as well.

Paging

The promises returned by searchItems() and searchGroups() also got a handy new nextPage() method to make it easier to sift through paginated results.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
searchItems({ q })
  .then(response => {
    if (response.nextPage) {
      r.nextPage()
        .then(responsePageTwo)
    }
  })

Reuse parameters

We added two new methods to @esri/arcgis-rest-request as helpers for passing repeat options through.

setDefaultRequestOptions()

Now, if you want to ensure that all requests include a custom option, you can use setDefaultRequestOptions().

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
import { request, setDefaultRequestOptions } from "@esri/arcgis-rest-request";

setDefaultRequestOptions({
  headers: { "Custom-Header": "Test Value" }
});

const url = `https://www.arcgis.com/sharing/rest/info`;

// the custom header will *always* be passed along
request(url)

You should not pass authentication to this method if your code runs in a shared environment like a web server that handles requests for more than one user.

withOptions()

If you'd like to selectively append common options to a specific method, you can use the new withOptions() method.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
import { request, withOptions } from "@esri/arcgis-rest-request";

const authenticatedRequest = withOptions({
  authentication: session
}, request);

// includes authenticated session
authenticatedRequest(url)

// does NOT include authenticated session
request(url)

Breaking Changes

In order to make the API more consistent and a little easier to navigate, we had to break a few 🍳s.

One portal package to rule them all (even for ArcGIS Online)

We consolidated four existing packages into a new one called @esri/arcgis-rest-portal. Whether you want to talk to ArcGIS Online or Enterprise, now you'll do this:

Use dark colors for code blocksCopy
1
2
# new
npm install @esri/arcgis-rest-portal

instead of this:

Use dark colors for code blocksCopy
1
2
3
4
5
# old
npm install @esri/arcgis-rest-items &&
@esri/arcgis-rest-users &&
@esri/arcgis-rest-groups &&
@esri/arcgis-rest-sharing

The table below lists methods in this package that have been deprecated, given a facelift, or given a new home.

OldNewPackage
serializeGroup()groups
addItemJsonData()addItemData()items
createItemInFolder({ folder })createItemInFolder({ folderId })items portal
~~`searchItems( stringopts )`~~[`searchItems( string
searchGroups( form, opts )[`searchGroups( stringopts
getItemResources( opts )getItemResources( id, opts? )items portal
getUserUrl()getUserUrl()auth portal
getPortalUrl()getPortalUrl()request portal
getPortal()getPortal()request portal
SearchQueryBuilderportal

@esri/arcgis-rest-request

The only breaking changes we made to request were to refactor an internal method and move a couple others into the new portal package.

OldNewPackage Name
getPortalUrl()getPortalUrl()request portal
getPortal()getPortal()request portal

If you work with private services (shhhh)

We didn't make many changes in @esri/arcgis-rest-auth, but one method moved and two others got simpler.

OldNewPackage Name
getUserUrl()getUserUrl()auth portal
`fetchToken(paramsopts)`fetchToken(opts)
`generateToken(paramsopts)`generateToken(opts)

@esri/arcgis-rest-routing

In this package, we renamed one constant.

OldNew
worldRoutingServiceARCGIS_ONLINE_ROUTING_URL

Geocoding addresses

In the interest of consistency, we renamed the geocoding package too.

Use dark colors for code blocksCopy
1
2
# new
npm install @esri/arcgis-rest-geocoding
Use dark colors for code blocksCopy
1
2
# old
npm install @esri/arcgis-rest-geocoder

We renamed one method (and one constant) as well.

OldNew
serviceInfo()getGeocodeService()
worldGeocoderARCGIS_ONLINE_GEOCODING_URL

Querying and editing feature layers

This package was also renamed. If you're already using queryFeatures() or making edits inside hosted feature layers, now you'll install this:

Use dark colors for code blocksCopy
1
2
# new
npm install @esri/arcgis-rest-feature-service

instead of this:

Use dark colors for code blocksCopy
1
2
# old
npm install @esri/arcgis-rest-feature-service

The feature-layer methods that were refactored or re-homed are listed below.

OldNewPackage
addFeatures({ adds })addFeatures({ features })
updateFeatures({ updates })updateFeatures({ features })
deleteFeatures({ deletes })deleteFeatures({ objectIds })
getLayer(url, options)getLayer(options)

Publishing and updating new hosted feature services

If you're already using rest-js to publish new hosted feature services, that package has a new (shorter) name too.

Use dark colors for code blocksCopy
1
2
# new
npm install @esri/arcgis-rest-service-admin

instead of this:

Use dark colors for code blocksCopy
1
2
# old
npm install @esri/arcgis-rest-feature-service-admin

After you save those seven keystrokes, everything else will be familiar.

Helper methods

In this release we also made the decision to stop documenting internal helper methods like appendCustomParams. In the future, undocumented methods may change without notice.

Breaking Changes for TypeScript developers

Each package now installs shared TypeScript typings automatically and re-exports them, so its no longer necessary to install a separate package yourself.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
// old
import { IPoint } from "@esri/arcgis-rest-common-types";
import { reverseGeocode } from "@esri/arcgis-rest-geocoder";

reverseGeocode({ x: 34, y: -118} as IPoint);

// new
import { IPoint, reverseGeocode } from "@esri/arcgis-rest-geocoding";

reverseGeocode({ x: 34, y: -118} as IPoint);

If you'd like to install the typings yourself, there is a more concise package name for that too.

Use dark colors for code blocksCopy
1
2
# new package name
npm install @esri/arcgis-rest-types

The table below lists interfaces and types that have been removed or renamed in the name of consistency and brevity. This also better aligns the names of options and response interfaces with their corresponding function.

Old Interface/TypeNew Interface/Type
esriFieldTypesFieldTypes
esriGeometryTypeGeometryType
esriUnitsUnits
IOauth2OptionsIOAuth2Options
IBulkGeocodingRequestOptionsIBulkGeocodeOptions
IGeocodeRequestOptionsIGeocodeOptions
IGeocodeParams
ISolveRouteRequestOptionsISolveRouteOptions
IEditFeaturesParamsISharedEditOptions
IQueryFeaturesParamsISharedQueryOptions
IQueryFeaturesRequestOptionsIQueryFeaturesOptions
IQueryRelatedRequestOptionsIQueryRelatedOptions
IAddFeaturesRequestOptionsIAddFeaturesOptions
IUpdateFeaturesRequestOptionsIUpdateFeaturesOptions
IDeleteFeaturesRequestOptionsIDeleteFeaturesOptions
IDecodeValuesRequestOptionsIDecodeValuesOptions
ILayerRequestOptionsIGetLayerOptions
IFeatureRequestOptionsIGetFeatureOptions
IAddToServiceDefinitionRequestOptionsIAddToServiceDefinitionOptions
ICreateServiceRequestOptionsICreateServiceOptions
IItemResourceAddRequestOptions
IGroupAddRequestOptionsICreateGroupOptions
IPagingParamsRequestOptionsIGetGroupContentOptions
IGroupIdRequestOptionsIUserGroupOptions
IGroupNotificationRequestOptionsICreateGroupNotificationOptions
ISearchRequestOptionsISearchOptions
IGroupUpdateRequestOptionsIUpdateGroupOptions
IItemIdRequestOptionsIUserItemOptions
IItemResourceRequestOptionsIItemResourceOptions
IItemAddResponseICreateItemResponse
IManageItemRelationshipRequestOptionsIManageItemRelationshipOptions
IItemDataAddRequestOptionsIAddItemDataOptions
IItemCrudRequestOptionsICreateUpdateItemOptions
IAddFolderRequestOptionsICreateFolderOptions
IItemAddRequestOptionsICreateItemOptions
IItemDataRequestOptionsIItemDataOptions
IItemRelationshipRequestOptionsIItemRelationshipOptions
IItemGroupResponseIGetItemGroupsResponse
IItemRequestOptions
IFolderIdRequestOptionsIFolderIdOptions
IItemUpdateResponseIUpdateItemResponse
IItemMoveResponseIMoveItemResponse
IItemUpdateRequestOptionsIUpdateItemOptions
IItemMoveRequestOptionsIMoveItemOptions
ISharingRequestOptionsISharingOptions
ISetAccessRequestOptionsISetAccessOptions
IGroupSharingRequestOptionsIGroupSharingOptions
IGetUserRequestOptionsIGetUserOptions
IInvitationRequestOptionsIGetUserInvitationOptions
INotificationIdRequestOptionsIRemoveNotificationOptions
IUpdateUserRequestOptionsIUpdateUserOptions
IParamBuilder
IParamsBuilder

That's it! We know that moving so much 🧀 is a hassle, but developers of the future send their thanks! 🎩

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