REST API versioning

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

Compatibility rules for JSON responses

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.

http://<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.

3/3/2017