John Foster

ArcGIS REST APIGetting Started

ArcGIS REST API

• Who is this talk talking to?• What are we going to cover in this talk?• This is intro + getting started

• Also check out: ArcGIS REST API: Advanced Techniques- Wed 2/12 1:30 PM 102B

• ArcGIS Online, MapViewer• Storymaps, Operations Dashboard, Insights• SDKs: JavaScript, Runtime, Python• ArcGIS Hub• Developer’s website• ArcGIS Pro• …and many others

Who is using REST?

Have portal, will REST

What is REST?

• REST == REpresentational State Transfer

• For distributed hypermedia systems (HTTP/HTTPS)

• First presented by Roy Fielding in 2000 • See https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

• URI “endpoint”• operations, or methods:

- GET- POST- PUT- PATCH- DELETE

• parameters• headers• response status code• response

HTTP/S protocol

https://developer.mozilla.org/en-US/docs/Web/HTTP

REST in action

• Let’s look at some REST

Examplehttps://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=json&SingleLine=Washington%20Convention%20Center%2C%20Washington%20DC&category=POI&outFields=*&forStorage=false

ExampleEndpoint (URI):https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates

Parameters:f=jsonSingleLine=Washington%20Convention%20Center%2C%20Washington%20DCcategory=POIoutFields=*forStorage=false

REST in action

• Let’s try a geocode

REST in action

• Let’s try a geocode – type this into a browser:

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=json&SingleLine=Washington%20Convention%20Center%2C%20Washington%20DC&category=POI&outFields=*&forStorage=false

REST in action

• Let’s try a geocode – create an HTML page:

<form method="post"action="https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"><label for="SingleLine">Point of interest:</label><input type="text"

name="SingleLine"><input type="hidden" name="category" value="POI"><input type="hidden" name="outFields" value="*"><input type="hidden" name="f" value="json"><input type="submit" value="Post">

</form>

REST in action

• Let’s try a geocode – create a shell script:

#!/bin/bash##################################################protocol="https://"host="geocode.arcgis.com"endpoint="/arcgis/rest/services/World/GeocodeServer/findAddressCandidates"url="${protocol}${host}${endpoint}"parameters="f=json&category=POI&outFields=*&SingleLine=${1}"echo "${url}?${parameters}"curl "${url}?${parameters}"

REST in action

• Let’s try a feature service – type this on a command line:

curl -G "https://services8.arcgis.com/LLNIdHmmdjO2qQ5q/arcgis/rest/admin/services/ufo_sightings_de/FeatureServer?f=json"

Get a token

• Developer dashboard: https://developers.arcgis.com/dashboard

• By script: https://developers.arcgis.com/labs/rest/get-an-access-token/

REST in action

• Let’s try a feature service – type this on a command line:

curl -G "https://services8.arcgis.com/LLNIdHmmdjO2qQ5q/arcgis/rest/admin/services/ufo_sightings_de/FeatureServer?f=json&token="

Pitfalls!• cURL only gets you so far• Very inflexible• Not handling parameters, auth, errors• Writing lots of (bad) code

Postman• https://www.getpostman.com/downloads/

Postman• ArcGIS tutorials:

https://developers.arcgis.com/labs/browse/?product=rest-api&topic=any

• ArcGIS REST API: https://github.com/esri-es/ArcGIS-REST-API

Postman• https://www.getpostman.com/downloads/• Great for managing collections of endpoints• Great for testing endpoints, API development• Not great for building an app

JavaScript• fairly easy to encode REST API calls with JavaScript• XMLHttpRequest• fetch• jquery• 3rd party libs, npm

JavaScript• XMLHttpRequest• https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest

JavaScript// construct the url yourself and don't forget to tack on f=jsonconst url = "https://www.arcgis.com/sharing/rest/community/users/dmfenton";url += "?f=json";var xhr = new XMLHttpRequest();xhr.onreadystatechange = function() {

if (xhr.readyState == XMLHttpRequest.DONE) {// make sure JSON response doesn’t indicate an errorif (!xhr.responseText.error) {xhr.responseText; //{firstName:"Daniel",description:”I’m a dev"...}

}}

}xhr.open('GET', url, true);xhr.send(null);

JavaScript• fetch• https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch

JavaScriptconst url = "https://www.arcgis.com/sharing/rest/community/users/dmfenton";fetch(url, {method: "POST", // set the request typeheaders: {"Content-Type": "application/x-www-form-urlencoded" // append the right header

},// concat and encode parameters, append f=jsonbody: encodeURIComponent("f=json")

}).then(response => {if (response.ok) { return response.json() } // dig out the json

}).then(response => {// trap for errors inside a 200 responseif (!response.error) { return response; }})

Many issues handling all this on your own:

• Lots of boiler plate code 🤕🤕• What are all the error codes? 🤷🤷🤷♀

• How do you handle authentication? 🤷🤷🤷♀

• How are dates supposed to be encoded? 🤷🤷🤷♀

• Proper encoding for objects? 🤷🤷🤷♀

• How do you manage tokens for federated servers? 🤷🤷🤷♀

• Refreshing authentication when necessary? 🤕🤕

Managing complexity

Is there a better way?

ArcGIS REST JS

@esri/arcgis-rest-js helps you

talk to ArcGIS Online and Enterprise

from modern browsers and Node.js.

ArcGIS REST JS

kind of analogous to ArcGIS API for Python

much different than the ArcGIS API for JavaScript

different goals and use cases

ArcGIS REST JS

Open source on GitHub

Code 🎛🎛 https://github.com/Esri/arcgis-rest-js

Doc 📚📚 https://esri.github.io/arcgis-rest-js

ArcGIS REST JS simplifiesimport { request } from "@esri/arcgis-rest-request";

request(url).then(response) // {firstName:"Daniel",description:"open source geodev" ... }.catch((error => {if(err.name === "ArcGISAuthError"){// handle and auth error

} else {// handle a regular error

}})

• Knows how to converse with ArcGIS portals- Authentication, token management- f=json - parameter encoding- uses FormData when required- clear and informative error handling

• but, not for- map and layer rendering- client-side analysis

ArcGIS REST JS value adds

Pass-through parameters// url, IRequestOptionsrequest(url, {

params: { // anything you want to pass to the endpointfoo: true,bar: "baz",attachment: File(),num: 999,when: Date().now() // etc.

},// httpMethod: "GET",// authentication// portal,// headers,// fetch})

Request is the foundationimport { geocode } from "@esri/arcgis-rest-geocoder";

// assumes you want to use ArcGIS Onlinegeocode("Washington Convention Center, Washington DC").then(response) // { ... candidates: [] }

// IRequestOptions is still availablegeocode("Washington Convention Center, Washington DC", {params: {

category: "POI",outFields: "*"

},authentication})

ArcGIS REST JS Goals• Ease the use of ArcGIS REST endpoints• Node.js and (modern) browsers• a la carte services• framework agnostic• align with JS ecosystem

ArcGIS REST JS Disclaimer• not a product, no roadmap• not a product, no official support• work in progress, compare https://developers.arcgis.com/rest/• open source, contributions welcome!

Demo

Location services- Geocode- Routing- Demographics- Analysis- Elevation- Packaging

What services are available?

ArcGIS Online and Enterprise- Users- Groups- Items

ArcGIS Enterprise- Server- Portal- Notebooks- Extensions

https://developers.arcgis.com/rest/

Resources• ArcGIS REST API https://developers.arcgis.com/rest/

• arcgis-rest-js code https://github.com/Esri/arcgis-rest-js

• arcgis-rest-js documentation https://esri.github.io/arcgis-rest-js

• Hosted Feature Service resource https://github.com/esri-es/ArcGIS-REST-

API/tree/master/HostedFeatureServices

• HTTP: https://developer.mozilla.org/en-US/docs/Web/HTTP

Resources• ArcGIS REST API https://developers.arcgis.com/rest/

• arcgis-rest-js code https://github.com/Esri/arcgis-rest-js

• arcgis-rest-js documentation https://esri.github.io/arcgis-rest-js

• Hosted Feature Service resource https://github.com/esri-es/ArcGIS-REST-

API/tree/master/HostedFeatureServices

• HTTP: https://developer.mozilla.org/en-US/docs/Web/HTTP

• cURL: https://curl.haxx.se/

Questions?

Print Your Certificate of Attendance

Print Stations Located in 150 Concourse Lobby

Tuesday12:30 pm – 6:30 pmExpoHall B

5:15 pm – 6:30 pmExpo SocialHall B

Wednesday10:45 am – 5:15 pmExpoHall B

6:30 pm – 9:30 pmNetworking ReceptionSmithsonian National Museumof Natural History

Download the EsriEvents app and find

your event

Select the session you attended

Scroll down to “Survey”

Log in to access the survey

Complete the survey and select “Submit”

Please Share Your Feedback in the App