Versioning in the Web API
The Web API is versioned as a single unified API and as its individual components. The Web API consists of a “core” into which plug “components” that provide the various areas of functionality. It is important to distinguish between the version of the overall Web API and to the versions of the components which make up the Web API. Each component also has a file version.
You can get the version information from the \Versions endpoint. The information returned is the component names, descriptions, API version, assembly version, and file version.
▪When a component is updated (for example, to improve performance or to resolve an issue), the “file version” is incremented.
▪When the behavior of any of the endpoints of the component changes, the “API version” of that component is incremented.
▪When “API version” of any component of the Web API is incremented, the “API version” of the overall Web API is also incremented.
For example, v1.1 of the Web API contains the following components:
▪API version 1.0 of the Intelligence.WebApi.Components.CaseData component. (The Case Data API is the same in versions 1.0 and 1.1 of the Web API.)
▪API version 1.0 of the Intelligence.WebApi.ExportData component. (This component was added in version 1.1 of the Web API.)
▪API version 1.1 of the Intelligence.WebApi.Components.Quotas component. (Its endpoints and response formats are different in versions 1.0 and 1.1 of the Web API.)
When making a request a client should specify the component API version that it requires by doing one of the following:
▪include an “X-Api-Version” header in the request
▪use an “Api-Version” query parameter.
The default version is 1.0.
The component and component API version for each endpoint can be found in the OpenApi specification as described in Section
OpenApi specification.
The requirement of the X-Api-Version header variable or the Api-Version query parameter enables the server version of the Web API to be updated before any clients that use the Web API. Because the client is sending the version number, the server can change its behavior to what it was at that version. Later, the client can be updated for the changed behavior of the new server version or to use new functionality the server might provide. If an updated client tries to make a request to an older version of the server and specifies a version which the server does not support, the server returns an error.
See