REST API versioning—ArcGIS REST APIs

A set of rules for versioning of the ArcGIS REST API has been established as the API evolves over a set of releases. In the case of the ArcGIS REST API, the input or parameters of a request are in the form of name-value pairs. The values themselves may be literals (name=value) for simple parameters, or JSON representations (name={<json-object>}) for more complex structures. The output is in the form of a JSON response. Therefore, "version" refers to the version of the input parameters and of the JSON response unless otherwise specified. The version is a property of the message exchanged and is not necessarily indicative of the version of the client or server.

Statement

The ArcGIS REST API will evolve such that the input parameters and the JSON responses will be version compatible. However, the actual input parameters as well as the responses may not be the same across different versions of the API.

Compatibility rules for input parameters

Requests are compatible irrespective of the order in which the parameters appear. In the following two examples, the order of the location and distance parameters are different.

https://<serviceResource>/<operation>?f=json&location={"x" : -118.15, "y" : 33.80}&distance=100

https://<serviceResource>/<operation>?f=json&distance=100&location={"x" : -118.15, "y" : 33.80}

Requests are compatible irrespective of the order in which the properties of the JSON parameters appear. In the following examples, the order of the x and y properties are different. However, clients should strive to maintain the order of the properties in the JSON parameters while issuing requests to the REST API.
```
https://<serviceResource>/<operation>?f=json&location={"x" : -118.15, "y" : 33.80}&distance=100
```
```
https://<serviceResource>/<operation>?f=json&location={"y" : 33.80, "x" : -118.15}&distance=100
```
New parameters may be added to future versions of requests. In the following example, a z value property and units parameter has been added. It is compatible with earlier examples because it includes all the parameters from the previous versions of the request. The REST API implementation is aware that new parameters may be added to future requests and is flexible enough to ignore parameters it is not aware of.
```
https://<serviceResource>/<operation>?f=json&location={"x" : -118.15, "y" : 33.80, "z" : 42.68}&distance=100&units=meters
```
Existing parameters cannot be removed from future versions of requests. The following example is not compatible with earlier examples because it does not include the distance parameter, which was present in the previous versions.
```
https://<serviceResource>/<operation>?f=json&location={"x" : -118.15, "y" : 33.80}
```
Existing properties cannot be removed from the JSON parameters in future versions of requests. The following example is not compatible with earlier examples because the JSON parameter location does not include the property y, which was present in the previous versions.
```
https://<serviceResource>/<operation>?f=json&location={"x" : -118.15, "z" : 42.68}&distance=100
```

Compatibility rules for JSON responses

Responses are compatible irrespective of the order in which the properties appear. In the following examples, the order of the x and y properties are different. Although a different order is possible, the REST API will strive to maintain the order of the properties in the JSON responses across different versions.
```
{ "x" : -118.15, "y" : 33.80 }
```
```
{ "y" : 33.80, "x" : -118.15 }
```
New properties may be added to future versions of the response. In this example, a new property z has been added. It is still compatible with earlier examples because it includes all the properties in the previous responses. Clients of the REST API should be aware that new properties may be added to future responses, and they should be flexible enough to ignore properties that they are not aware of.
```
{ "x" : -118.15, "y" : 33.80, "z" : 42.68 }
```
Existing properties cannot be removed from future versions of the response. In the following example, the property y is missing, which was present in earlier versions.
```
{ "x" : -118.15, "z" : 42.68 }
```

The version parameter

While the request parameters and JSON responses are compatible with previous versions, for certain output formats (f=lyr), clients can explicitly specify the version of the requests they are issuing and the response that they want. They can specify this with a version parameter v.

https://<mapserviceResource>?f=lyr&v=10.0&v=9.3

In the above request, the client has explicitly indicated that the request it is issuing, as well as the response it is expecting, should be 10.0 compatible.

Current version

The version of the deployed API is indicated on the home page of the Services Directory. This informs the clients of the current version of the API. The API responses are compatible with previous versions. If a client makes a request in a version greater than the current version, the API returns responses in its current version.

Exceptions

While the above versioning statement and compatibility rules will be adhered to as much as possible, in certain rare situations it may be necessary to break compatibility. The reasons can vary, from an unsupported operation to a change in the structure of the request or response. If a change is required, it will be documented and visible.