The ArcGIS REST Web Service is based on two clear principles:
Every GIS Service published on an ArcGIS Server is considered a resource and can be accessed through a URL such as http://<host name>/arcgis/rest/<ServiceName>. This URL is also known as REST endpoint.
- Each resource has:
- Properties that describe it
- Operations that can be performed on the resources (optional)
- Child resources (optional)
An operation is an action on a resource that triggers the state transfer of the resource and/or creates new resources. A child resource is a resource that lives within the context of its parent and inherits the properties of its parent. A child resource can also have its own properties and support operations that can be performed on it. A resource creates a hierarchy of endpoints for its child resources and operations which are accessed by a URL.
Geoprocessing REST services
A geoprocessing service is a resource and accessed through a URL. The URL format for geoprocessing service is http://<server name>/<instance name>/rest/services/<Service Name>/GPServer, for example, http://myServer/ArcGIS/rest/services/BufferPoints/GPServer. A geoprocessing service has properties such as Service Description, Tasks, Execution Type, and Result Map Server. The geoprocessing tasks that are published within a geoprocessing service are its child resources. The geoprocessing service by itself does not have any operations but the tasks support a submitJob or execute operation. The tasks in a geoprocessing service inherit the Execution Type and Result Map Server properties and has additional properties such as task Description, task Parameters, and so on. The properties of the service and the task are determined by the publisher of the service and cannot be modified by clients.
The figure below shows the hierarchy of geoprocessing REST resources. Notice that geoprocessing service properties shown in orange, such as Execution Type, Maximum number of records (Max no. of Records in the illustration), and Result Map Server, are inherited by every geoprocessing task.
Note:
The properties of the geoprocessing service and the tasks are determined by the publisher of the service and cannot be modified by clients.
Geoprocessing tasks
A geoprocessing task is a child resource of the geoprocessing service. A geoprocessing service can have one or more tasks. Consider a geoprocessing task as a geoprocessing tool managed by the server. The tool is executed at the server when a client sends a request with appropriate input parameter values. When the tool has executed successfully, the output parameter values will be returned to the client. The access URL for a geoprocessing task is http://<gpservice-url>/<taskName>, for example, http://myserver/ArcGIS/rest/services/BufferPoints/GPServer/BufferPoints.
Learn more about geoprocessing tasks in REST
Execution type
The geoprocessing functionality of a geoprocessing task can be straightforward and may take a few seconds to execute on the server, or it can support advanced functionality—processing large datasets—and may take longer to execute. Therefore, the REST API provides two options to run the geoprocessing task on the server.
- Synchronous: Synchronous tasks are suitable for fast running tasks. In synchronous tasks, the client sends a request to run the task and the results of the task are sent as a response to the client.
- Asynchronous: Asynchronous tasks are suitable for long running jobs. In asynchronous tasks, the server returns a job ID which the client uses to poll for task status. When the status is completed, the results are created as child resources of the job which the client can access using its job ID.
Result map server
The result map server is a dynamic map service that accompanies a geoprocessing service to visualize the geoprocessing results. Each geodataset output parameter of a geoprocessing task will be added as a layer to the map service. The visualization of the layers is determined by the symbology defined at the time of publishing. Since it is a dynamic map service, clients can add the map service or the map service layers to web applications. The clients can also perform operations such as Identify, Find and Export Map on the map service and Query, Generate renderers and access features on the map service layers.
Maximum number of records
The maximum number of records property determines the number of output features or records returned by the service. If the number of output records or features created by a geoprocessing task exceeded the maximum number of records, the service will not return any features or records. The clients can identify such cases by examining the exceeded transfer limit property of the feature set or record set returned by the task. The exceeded transfer limit property will be set to true when the number of records and features of the output parameter exceed the maximum number of records specified by the service.
Viewing the service page in a web browser
Each ArcGIS Server has a services directory, accessible with a URL, and each service on the server has its own service page, also accessible with a URL. The geoprocessing REST service properties described above can be examined on the service page in a web browser. The service page is primarily used by web developers to understand the capabilities of a service. Even if you're not a web developer, you'll find that the services page will help you understand how decisions you make when publishing a service affect how web developers use your service and the tasks within.
After you've successfully published a geoprocessing service in ArcGIS for Desktop, a new geoprocessing service is added to your ArcGIS Server Connection in the Catalog window. To view the services page for your service, right-click the service and select Service Properties. This will open the Service Editor. In the Service Editor, click the Geoprocessing tab found under Capabilities. The REST URL value, illustrated below, is the URL to the service page.
Copy and paste the REST URL into your browser address bar to view the service page. The information listed on the REST URL page directly relates to the properties that you defined when publishing the geoprocessing service. The illustration below shows the properties that were specified in the Service Editor when publishing and the corresponding properties as seen in the service page.
Note that the geoprocessing tasks of the service in the web browser are listed with an HTML link. Each link will lead to a task page where you can find information on task properties and supported operation.