Both the Java and .NET instances of the REST API work out-of-the-box without requiring special configuration. However, if you export and deploy the REST instance elsewhere, or if you needed to change the defaults, an understanding of the various configuration points is required.
From the API perspective, both Java and .NET instances are identical. However, given they are disparate platforms, they differ in their configuration settings and so are discussed separately.
| Configuring the Java instance | Configuring the .NET instance |
The Java configuration consists of configuring two files:
server.properties: found in the /WEB-INF/classes folder and
contains information about the ArcGIS Server that the REST instance connects
to.
rest-config.properties: found in the /WEB-INF/classes/resources folder and contains information such as the REST cache policies, Google Maps key, and the API reference URLs.
The information about the ArcGIS Server to connect to is configured in server.properties.
com.esri.rest.HOST property.
com.esri.rest.DOMAIN, com.esri.rest.USER_NAME and com.esri.rest.PASSWORD properties. These properties provide the user's domain, user name, and password, respectively. If the password provided is encrypted, then another property com.esri.rest.PASSWORD_ENCRYPTED should be set to true.
com.esri.rest.SOAP_URL property. This URL is used to generate the SOAP URLs for various services in the Services Directory as well as to encode these URLs in the lyr files and nmf files generated for some of the services. If certain SOAP end-points are also available through HTTPS, the HTTPS URL can be configured using the com.esri.rest.SOAP_HTTPS_URL property.
com.esri.rest.SECONDARY_HOSTS property. The cluster type is configured using the com.esri.rest.SERVER_CLUSTER_TYPE property. Two types of server clusters are possible: failover and roundrobin.A typical server.properties file looks like the following:
com.esri.rest.HOST=myserver com.esri.rest.DOMAIN=mydomain com.esri.rest.USER_NAME=myusername com.esri.rest.PASSWORD=mypassword com.esri.rest.PASSWORD_ENCRYPTED=false com.esri.rest.SOAP_URL=http://myserver:8399/arcgis/services com.esri.rest.SOAP_HTTPS_URL=https://myserver:8343/arcgis/services com.esri.rest.SECONDARY_HOSTS=myserver2,myserver3 com.esri.rest.SERVER_CLUSTER_TYPE=roundrobin
In order to view certain map services with the ArcGIS JavaScript Extension for the Google Maps API library directly from the Services Directory, you must obtain a Google Maps API Key from Google. The website URL you provide when signing up for this key should be the base URL of your Services Directory. For a default installation, the URL to provide for the key would be http://<host>:8399/arcgis/rest
Once you have obtained the key, you can configure it using the jsapi.gmaps.key property in rest-config.properties.
To disable Services Directory, you can set the config.services-directory-disabled property to true in rest-config.properties. This property is false by default. Note that you can disable and enable Services Directory at runtime as well by using the REST Admin.
The REST API caches information pertaining to catalogs and services to boost performance. The various cache configuration options you can set in rest-config.properties are discussed here.
config.cache.clear-cache-mode property. The possible values are manual, scheduled and periodic. The default is manual.
manual mode, the cache is never cleared automatically. You need to
explicitly clear the cache by using the REST Admin.
scheduled
mode, you schedule a time and the cache is cleared daily at that time.
periodic mode, you set a periodic interval and the cache is cleared periodically after the set interval.scheduled, you can configure the scheduled cache clearance time using the config.cache.clear-cache-time property. The value of this is the time of the day based on a 24 hour clock. For example, if you want to schedule the REST Cache to be cleared at 11 pm, you should set config.cache.clear-cache-time=23:00.
periodic, you can configure the cache clearance interval in minutes using the config.cache.clear-cache-interval property. For example, if you want to periodically clear the REST Cache every 60 minutes, you should set config.cache.clear-cache-interval=60.
config.cache.cached-objects-limit property. For example, to configure a maximum of 200 objects, you should set config.cache.cached-objects-limit=200. The default is 100.
You need to configure the properties pertaining to REST API ports only if you have a mix of standard (available over HTTP) and encrypted (available over HTTPS only) services. This is because if you have a mix of services, the Services Directory needs to generate full URLs for services and folders that are in the other scheme. On the other hand, if the services are all in the same scheme, Services Directory generates only relative URLs, thereby negating the need to configure the ports. The properties for ports are in rest-config.properties.
You can configure the standard HTTP port with the config.http-port property and the HTTPS port with the config.ssl-port property.
If you have a reverse proxy set up for accessing the REST API, you can configure the reverse proxy's standard HTTP port with the config.reverse-proxy-http-port property and the reverse proxy's HTTPS port with the config.reverse-proxy-ssl-port property.
A typical configuration of the port properties would look like this:
config.http-port=8399 config.ssl-port=8343 config.reverse-proxy-http-port=80 config.reverse-proxy-ssl-port=443
Services Directory gives you the ability to view map services in the three JavaScript libraries - ArcGIS JavaScript API, ArcGIS JavaScript Extension for the Google Maps API, and ArcGIS JavaScript Extension for Virtual Earth. You can configure the URLs to various resources for these libraries using the properties in rest-config.properties discussed here.
jsapi.arcgis - URL
to the ArcGIS JavaScript library
jsapi.arcgis.sdk -
URL to the ArcGIS JavaScript library SDK
jsapi.arcgis.css -
URL to the ArcGIS JavaScript library CSS
jsapi.ve - URL to
the Virtual Earth Extender JavaScript library
jsapi.ve.sdk - URL
to the Virtual Earth Extender JavaScript library SDK
jsapi.ve.terms -
URL to the Microsoft Virtual Earth Terms and Conditions
jsapi.gmaps - URL
to the Google Maps Extender JavaScript library
jsapi.gmaps.sdk -
URL to the Google Maps Extender JavaScript library SDK
jsapi.gmaps.terms - URL to the Google Maps Terms and ConditionsA typical configuration of the JavaScript API URLs would look like this:
jsapi.arcgis=http://serverapi.arcgisonline.com/jsapi/arcgis?v=1 jsapi.arcgis.sdk=http://resources.esri.com/arcgisserver/apis/javascript/arcgis jsapi.arcgis.css= http://serverapi.arcgisonline.com/jsapi/arcgis/1/js/dojo/dijit/themes/tundra/tundra.cssjsapi.ve=http://serverapi.arcgisonline.com/jsapi/ve?v=1 jsapi.ve.sdk=http://resources.esri.com/arcgisserver/apis/javascript/ve jsapi.ve.terms= http://www.microsoft.com/virtualearth/product/terms.htmljsapi.gmaps=http://serverapi.arcgisonline.com/jsapi/gmaps?v=1 jsapi.gmaps.sdk=http://resources.esri.com/arcgisserver/apis/javascript/gmaps jsapi.gmaps.terms=http://code.google.com/apis/maps/terms.html
Services Directory provides context sensitive REST API Reference links on every page of the Services Directory. The URLs for these links can be configured in rest-config.properties and are discussed in this section.
The base.url property
should point to
the base URL of the REST API SDK. By default it points to the REST SDK installed with the server:
base.url=http://<host>:8399/arcgis/sdk/rest
All properties following the base.url property in the rest-config.properties file are relative URLs to the API reference topic for a resource or operation. For example, the mapserver=index.html?mapserver.html property is the relative URL to the API reference topic for the map service resource.
On certain platforms and configurations such as a distributed server configuration on certain Linux systems, there is a lag between the time when a dynamic tile is created and the time when the system makes it available for access. You can use the config.generated-tile-access-timeout property in rest-config.properties to set the maximum amount of time in seconds that the REST API cache will wait for a dynamically generated tile to be made available by the system before it returns with an HTTP 404. For example, if you want to set this timeout to 60 seconds, you should set config.generated-tile-access-timeout=60.
The .NET configuration is stored in the rest.config file found in the root folder.
The information about the ArcGIS Server to connect to is configured in the GISServer element of the rest.config file.
ServerName element.
SoapUrl element This URL is used to generate the SOAP URLs for various services in the Services Directory as well as to encode these URLs in the lyr files and nmf files generated for some of the services. If certain SOAP end-points are also available through HTTPS, the HTTPS URL can be configured using the SoapSslUrl element.EncodedString element inside of the Identity element. This value is set during the Web Applications Post Install using the credentials specified for the GIS Server Web Services Account.
A typical GISServer element in the rest.config file looks like the following:
<GISServer>
<ServerName>myserver</ServerName>
<SoapUrl>http://myserver/arcgis/services</SoapUrl>
<SoapSslUrl>https://myserver/arcgis/services</SoapSslUrl>
<Identity>
<EncodedString>slzH73QPaprcEFI/fL6Jco0fj6qp4MbccJJN+eP2wtU=</EncodedString>
</Identity>
</GISServer>
To disable Services Directory, you can set the enabled attribute to false in the ServicesDirectory element. This property is true by default. Note that you can disable and enable Services Directory at runtime as well by using the REST Admin.
The REST API caches information pertaining to catalogs and services to boost performance. The various cache configuration options you can set in the Cache element of the rest.config file are discussed here.
mode attribute. The possible values are manual, scheduled and periodic. The default is manual.
manual mode, the cache is never cleared automatically. You need to
explicitly clear the cache by using the REST Admin.
scheduled
mode, you schedule a time and the cache is cleared daily at that time.
periodic mode, you set a periodic interval and the cache is cleared periodically after the set interval.scheduled, you can configure the scheduled cache clearance time using the Time child element. The value of this is the time of the day based on a 24 hour clock. For example, if you want to schedule the REST Cache to be cleared at 11 pm, you should set <Time>23:00</Time>.
periodic, you can configure the cache clearance interval in minutes using the Period child element. For example, if you want to periodically clear the REST Cache every 60 minutes, you should use <Period>60</Period>.
A typical Cache element in the rest.config file looks like the following:
<Cache mode="manual"> <Period>5</Period> <Time>00:00</Time> </Cache>
You need to configure the properties pertaining to REST API ports only if you have a mix of standard (available over HTTP) and encrypted (available over HTTPS only) services. This is because if you have a mix of services, the Services Directory needs to generate full URLs for services and folders that are in the other scheme. On the other hand, if the services are all in the same scheme, Services Directory generates only relative URLs, thereby negating the need to configure the ports.
You can configure the standard HTTP port with the Port element and the HTTPS port with the SslPort property.
A typical configuration of the port properties would look like this:
<Port>80</Port> <SslPort>443</SslPort>
Services Directory gives you the ability to view map services in the three JavaScript libraries - ArcGIS JavaScript API, ArcGIS JavaScript Extension for the Google Maps API, and ArcGIS JavaScript Extension for Virtual Earth. You can configure the resources for these libraries using the JsApi child elements discussed here.
ArcGIS - URL to the ArcGIS JavaScript library
ArcGISSDK - URL to the ArcGIS JavaScript library SDK
VE - URL to the Virtual Earth Map Control JavaScript library
VEExtender - URL to the Virtual Earth Extender JavaScript library
VETerms - URL to the Microsoft Virtual Earth Terms and Conditions
ArcGISVESDK - URL to the Virtual Earth Extender JavaScript library SDK
GMaps - URL to the Google Maps JavaScript library
GMapsExtender - URL to the Google Maps Extender JavaScript library
GMapsTerms - URL to the Google Maps Terms and ConditionsArcGISGMapsSDK - URL to the Google Maps Extender JavaScript library SDK
GMapsKey - A Google Maps API Key from Google. This is required in order to view certain map services with the ArcGIS JavaScript Extension for the Google Maps API library directly from the Services Directory. The website URL you provide when signing up for this key should be the base URL of your Services Directory. For a default installation, the URL to provide for the key would be http://<host>/arcgis/rest
A typical configuration of the JavaScript API URLs would look like this:
<JsApi>
<ArcGIS>http://serverapi.arcgisonline.com/jsapi/arcgis?v=1</ArcGIS>
<ArcGISSDK>http://resources.esri.com/arcgisserver/apis/javascript/arcgis</ArcGISSDK>
<VE>http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.1</VE>
<VEExtender>http://serverapi.arcgisonline.com/jsapi/ve?v=1</VEExtender>
<VETerms>http://www.microsoft.com/virtualearth/product/terms.html</VETerms>
<ArcGISVESDK>http://resources.esri.com/arcgisserver/apis/javascript/ve</ArcGISVESDK>
<GMaps>http://maps.google.com/maps?file=api&v=2</GMaps>
<GMapsExtender>http://serverapi.arcgisonline.com/jsapi/gmaps?v=1</GMapsExtender>
<GMapsTerms>http://code.google.com/apis/maps/terms.html</GMapsTerms>
<ArcGISGMapsSDK>http://resources.esri.com/arcgisserver/apis/javascript/gmaps</ArcGISGMapsSDK>
<GMapsKey><!--GMaps key goes here--></GMapsKey>
</JsApi>
Services Directory provides context sensitive REST API Reference links on every page of the Services Directory. The URLs for these links can be configured using the ApiHelp element which is discussed in this section.
The baseUrl attribute of the ApiHelp element should point to the base URL of the REST API SDK. By default it points to the REST SDK installed with the server:
baseUrl="http://<host>/arcgis/SDK/REST/index.html?"
All child elements of the ApiHelp element in the rest.config file contain relative URLs to the API reference topic for a resource or operation. For example, in the configuration snippet below, the Catalog element contains the relative URL to the API reference topic for the catalog resource.
<ApiHelp baseUrl="http://myserver/arcgis/SDK/REST/index.html?">
<Catalog>catalog.html</Catalog>
...
</ApiHelp>