In order to successfully use the Spatial Data Server (SDS) REST API, you must understand how to construct a URL and interpret the response. All resources (e.g. feature services, layers) and operations exposed by the REST API are accessible through a hierarchy of endpoints. This tutorial will help you understand the REST API by demonstrating the adminstration and use of the SDS via the html view of the Services Directory.

Creating data sources and services

1. Determine the adminstrative endpoint

When using the REST API, you must know the well-known endpoint from which to administer data sources and services.  The administrative root is available at the following URL:

http://<web server hostname>/<SDS instance name>/admin

Where:

• <web server hostname> is the name (and port) of the web server on which the SDS was configured.
• <SDS instance name> is the virtual directory defined when the SDS was installed.  The default value is "arcgis".
• admin represents the path to access the administrative root for the SDS.  The administrative root page presents options for creating and exploring data sources and services.

For example, to get to the administrative root of an SDS instance on a Web server with the hostname "www.myserver.com", use the URL:

http://www.myserver.com/arcgis/admin

2. Create a data source

From the administrative root page, click on the Datasource resource to display the Datasources page.  This page will list all data sources available for the SDS instance (empty upon initial install).  Click the Create datasource link to display the Create Datasource page which presents a dialog to enter connection parameters for a database instance.  



The following parameters are included in the createDatasource operation:

• Name - Required. Descriptive name of the data source.  Will be listed in the Datasources page.
• Description - Optional. More details on the data source.
• Server - Required.  The name of the machine on which the relational database is running and the name of the database instance.  For SQL Server, the format is server\SQL Server instance name. 
• Database - Required for some relational databases.  SQL Server instances require a database. 
• User Name - Required if using database authentication.  Determines which tables and views are accessible within the database.
• Password - Required if using database authentication. Password for user defined by User Name.
• Use Database Authentication - If Yes, the identity defined in this operation (User Name/Password) are used when connecting to the database instance.  If No, the identity of the SDS application is used.
• Format - The format of the response when the createDatasource operation is called.

Click the Create Datasource button to create the data source for use by the SDS.  If successful open the data source to view tables and views within the database instance for the defined user:

3. Create a service

Use the data source when creating a feature service. From the administrative root page, click on the Services resource to display the Services page.  This page will list all Services for the SDS instance (empty upon initial install).  Click the Create Service link to display the Create Feature Service page which presents a dialog to enter a service definition.  The service definition consists of a Feature Service Object defined using json. 

Use the following service as a guide. It contains an administrative section ("adminServiceInfo") to define service details, such the name and the database the layers in the service will use. The content section ("layers") defines administrative details for each layer (table name and geometry field), geometry type, extent, rendering info, and capabilities, such and query and editing.

{
  "adminServiceInfo": {
    "name": "WorldDataService",
    "type": "FeatureServer",
    "status": "Started",
    "maxRecordCount": 1000,
    "database": {
      "datasource": {
        "name": "Production Sedona"
      }
    }
  },
  "layers": [
    {
      "adminLayerInfo": {
        "tableName": "Demo.dbo.WorldCities_Geographic",
        "geometryField": {
          "name": "Shape"
        }
      },
      "name": "WorldCitiesGeographic",
      "type": "Feature Layer",
      "geometryType": "esriGeometryPoint",
      "extent": {
        "xmin": -180,
        "ymin": -90,
        "xmax": 180,
        "ymax": 90,
        "spatialReference": {
          "wkid": 4326
        }
      },
      "capabilities": "Create,Delete,Query,Update,Editing"
    }
  ]
}
            

Using services

1. Determine the well-known user endpoint

When using the REST API, you must know the well-known endpoint, which represents the services catalog. The services catalog lists feature services hosted by the SDS instance.  Layers within each feature services can be queried and/or editing depending on their capabilities. 

http://<web server hostname>/<SDS instance name>/rest/services

Where:

• <web server hostname> is the name (and port) of the web server on which the SDS was configured.
• <SDS instance name> is the virtual directory defined when the SDS was installed.  The default value is "SDS".
• rest/services represents the path to access feature services hosted by the SDS instance.

For example, to get to the user root of an SDS instance on a Web server with the hostname "www.myserver.com", use the URL:

http://www.myserver.com/arcgis/rest/services

2. Navigate using Services Directory

When you enter the URL endpoint for the user root in your browser, you will see Services Directory. Each Spatial Data Server instance provides a Services Directory to navigate through the list of feature services and their contents.

• If you are unfamiliar with Services Directory, you should read the Services Directory overview.
• Navigate through the feature services on your server and see how the URL changes.

3. Understand the documentation

The REST API documentation has topics on resources (databases, tables) and and operations as well as some introductory and reference topics. The hierarchy of resources and operations listed in the table of contents matches the hierarchy of the API itself. Each topic contains a description, URL parameters and examples, and JSON object response examples and explanations.

• The top node is Services Catalog.
• Under Services Catalog, you will see a list of services which contain one or more layers (tables or views with at least one spatial column).
• For each layer you may see a set of operations: query, add features, update features, delete features, and apply edits. Spatially enabled layers (tables) will offer additional operation parameters.

4. Create a URL and see the response

When using the REST API, you need to construct URLs. Services Directory can help you generate URLs that include both the reference to a resource and any parameters. A URL with parameters will have the following syntax:

http://<resource-url>?<parameter1=value1>&<parameter2=value2>

Where:

• http://<resource-url> is the URL to a given resource.
• ? denotes the beginning of a parameter list.
• parameter1=value1 is a name-value pair.

Almost all resources have an f parameter. This parameter determines the output format. For more information, you should review Output Formats.

To retrieve information about a table in a JSON object, you would use a URL similar to the following:

http://myserver/arcgis/rest/services/WorldDataService/FeatureServer/0?f=json

The response is in JSON format and looks similar to the following.

If you want the JSON object response to be more readable, you can use pjson. This option should only be used for debugging purposes since it takes longer to process the response.

http://myserver/arcgis/rest/services/WorldDataService/FeatureServer/0?f=pjson

{
  "currentVersion" : 10.1, 
  "id" : 0, 
  "name" : "WorldCitiesGeographic", 
  "type" : "Feature Layer", 
  "displayField" : "", 
  "description" : "", 
  "copyrightText" : "", 
  "supportsRollbackOnFailure" : true, 
  "geometryType" : "esriGeometryPoint", 
  "minScale" : 0, 
  "maxScale" : 0, 
  "extent" : {
    "xmin" : -180, 
    "ymin" : -90, 
    "xmax" : 180, 
    "ymax" : 90, 
    "spatialReference" : {
      "wkid" : 4326
    }
  }, 
  "hasAttachments" : false, 
  "htmlPopupType" : "esriServerHTMLPopupTypeNone", 
  "objectIdField" : "OBJECTID", 
  "globalIdField" : "", 
  "typeIdField" : "", 
  "fields" : [
    {
      "name" : "OBJECTID", 
      "type" : "esriFieldTypeInteger", 
      "alias" : "OBJECTID", 
      "sqlType" : "sqlTypeInteger", 
      "nullable" : false, 
      "editable" : false, 
      "domain" : null
    }, 
    {
      "name" : "Shape", 
      "type" : "esriFieldTypeGeometry", 
      "alias" : "Shape", 
      "sqlType" : "sqlTypeGeometry", 
      "nullable" : true, 
      "editable" : true, 
      "srid" : 4326, 
      "domain" : null
    }, 
    {
      "name" : "CITY_NAME", 
      "type" : "esriFieldTypeString", 
      "alias" : "CITY_NAME", 
      "sqlType" : "sqlTypeNVarchar", "length" : 30, 
      "nullable" : true, 
      "editable" : true, 
      "domain" : null
    }, 
    {
      "name" : "CNTRY_NAME", 
      "type" : "esriFieldTypeString", 
      "alias" : "CNTRY_NAME", 
      "sqlType" : "sqlTypeNVarchar", "length" : 30, 
      "nullable" : true, 
      "editable" : true, 
      "domain" : null
    }
  ], 
  "types" : [], 
  "templates" : [], 
  "supportedQueryFormats" : "JSON", 
  "maxRecordCount" : 1000, 
  "capabilities" : "Create,Delete,Query,Update,Editing"
}

In another example, you can query the contents of a layer. In this case, you would use the query operation. For this operation, you need to define an attribute and/or a spatial query. Some parameters are optional and some are required. These requirements are noted in the documentation. An example URL to return the geometry for all rows in a table is:

http://myserver/arcgis/rest/services/WorldDataService/FeatureServer/0/query?where=1=1&f=html

The above URL returns the response in HTML format - you should see the query dialog and the geometry coordinates and spatial reference listed for each row: