Scripting with ArcGIS REST API

ArcGIS Server is administered purely through web service requests to ArcGIS REST API. (Even when you use ArcGIS Server Manager to administer your server, calls to the REST API are being made on the back end.) To write scripts that administer ArcGIS Server, you need to choose a scripting language that allows you to construct URLs, make HTTP requests, and parse HTTP responses. The examples in this help system use Python.

It's important to note that using ArcGIS REST API does not require Esri software on the machine from which you run the script. All you need is an environment where you can make HTTP requests to your GIS server.

Note:

Click Overview for the web version of the ArcGIS REST API reference.

Getting started with server administration using ArcGIS REST API

To use the REST API, you create an HTTP request for the operation you want to perform and include the required parameters for that operation; for example, the following HTTP request joins a new machine to your site:

http://gisserver.domain.com:6080/arcgis/admin/machines/registermachineName=GISSERVER1.DOMAIN.COMadminURL=http://GISSERVER1.DOMAIN.COM:6080/arcgis/admin

A easy way to familiarize yourself with the administrative operations available and their required parameters is to use the ArcGIS Server Administrator Directory.

Using the Administrator Directory

The ArcGIS Server Administrator Directory is a web application that can help you write administrative scripts for ArcGIS Server. The Administrator Directory is typically available at http://gisserver.domain.com:6080/arcgis/admin.

Think of the Administrator Directory as a road map to ArcGIS Server resources exposed through the REST API. You can browse the links in the Administrator Directory to learn which URLs and parameters to use in your administrative web service requests. You can then formulate these requests and send them over HTTP using a scripting language of your choice.

Try using the Administrator Directory to perform an administrative task. Note the parameters you are required to enter and examine the URL in your browser's address bar as you make the request to the server. Web developer tools such as Fiddler or Firebug can be useful to see the full body of the request and response. This information is extremely valuable when you're attempting to construct your own administrative HTTP requests through Python or another scripting language.

Although you can use the Administrator Directory interactively to actually perform administrative tasks, this web application is best used as a learning tool to help you get familiar with the REST API. The intended web application for ArcGIS for Server administration is ArcGIS Server Manager.

Getting and using a token in scripts

Whenever you log in to Manager or the Administrator Directory, you need to provide the user name and password of an account that has administrative or publisher privileges to ArcGIS Server. The same concept applies when you write scripts. You are required to programmatically submit a name and password to the server. The server returns a token, which is a special string of characters that proves to the server you have been authenticated to perform certain types of actions. You must include this token in any web service requests you make to the server.

The token does not last forever; it is designed to time out so it cannot be stolen and used indefinitely by a malicious user. You have to request a new token each time you run your script (but not each time you make a request).

The following Python function requests a token. The server name, port number, user name, and password are provided as arguments.

Request an administrative token from ArcGIS Server.

def getToken(username, password, serverName, serverPort):
    # Token URL is typically http://server[:port]/arcgis/admin/generateToken
    tokenURL = "/arcgis/admin/generateToken"
    
    # URL-encode the token parameters:-
    params = urllib.urlencode({'username': username, 'password': password, 'client': 'requestip', 'f': 'json'})
    
    headers = {"Content-type": "application/x-www-form-urlencoded", "Accept": "text/plain"}
    
    # Connect to URL and post parameters
    httpConn = httplib.HTTPConnection(serverName, serverPort)
    httpConn.request("POST", tokenURL, params, headers)
    
    # Read response
    response = httpConn.getresponse()
    if (response.status != 200):
        httpConn.close()
        print "Error while fetch tokens from admin URL. Please check the URL and try again."
        return
    else:
        data = response.read()
        httpConn.close()
           
        # Extract the token from it
        token = json.loads(data)        
        return token['token']

Working with requests and responses

To make a web service request of ArcGIS Server, you need to formulate the URL for the action you want to take as well as the required parameters for that action. One of the required parameters on a secured server is a token like the one generated above.

All administrative actions produce a web service response, which you'll typically request in JavaScript Object Notation (JSON) format. Scripting languages such as Python have libraries that can parse, or read, a JSON response. Sometimes you just want to get the HTTP status code to find out if your request succeeded (for example, a code of 200 means OK). Other times, the response may have data, like log messages, that you want to further parse and examine.

See the various code examples in this help book to understand how you might programmatically send a request to ArcGIS Server and work with a response.