Scripting with the ArcGIS Server Administrator API

ArcGIS Server is administered purely through RESTful web service requests to the Administrator API. (Even when you use ArcGIS Server Manager to administer your server, calls to the Administrator 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 the ArcGIS Server Administrator API does not require any 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.

Getting started with the ArcGIS Server Administrator API

To use the Administrator 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://MyServer:6080/arcgis/admin/machines/registermachineName=SERVER1.DOMAIN.COMadminURL=http://SERVER1.DOMAIN.COM:6080/arcgis/admin

A simple 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://<server name>:6080/arcgis/admin.

Think of the Administrator Directory as a road map to ArcGIS Server resources exposed through the Administrator API. You can navigate 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 Administrator 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 you 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 that 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.

Requests 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.