- APIs: Application Programming Interface (API) refers to a software layer that allows multiple software applications to communicate with each other.
- Endpoints: The set of services associated with an endpoint.
- Active: The set of services that are active, supported, and updated.
- Deprecated: Development on a service has ended. Updates and support are limited to bug fixes only.
- Decommissioned: Indicates that a service or set of services has ended and the service or set of services are no longer available.
Avalara API versioning uses the following format:
n.x.y
where
n indicates a major version that can include incompatible API changes
x indicates a minor version with backward-compatible added functionality
y indicates a patch version with backward-compatible bug/security fixes
In addition to the version, Avalara domains identify the resource, regardless of a version. As such, the domain to Avalara URLs remains consistent across versions.
For example, a domain api.avalara.com would remain for current and future version for different Avalara services:api.avalara.com/service/resource
Maintaining backward compatibility is important to Avalara and with that in mind, Avalara generally maintains backward compatibility for at least n-2 releases (where, as indicated above, n indicates the major version).
The standard policy for Avalara APIs is:
- deprecate the n-2 version after the n version is released.
- decommission the n-2 version 18 months after version n is released.
API releases n and n-1 will continually be active and supported.
Deprecated Release: Customers on release n-2 should migrate to the latest version once it is released.
Important: 18 months after release n is generally available (GA), release n-2 will be decommissioned and can no longer be accessed. Attempting to access a decommissioned version will result in an HTTP 400-Bad Request error. The error includes a “version-too-old” message.
Review the following table below for an example:
| Version | Release 1.0.0 | Release 2.0.0 | Release 3.0.0 |
| Release Date | 07/15/2023 | 3/25/2020 | 11/30/2017 |
| Deprecation date | Active | Active | 07/15/2023 |
| Decommission Date | Active | Active | 1/15/2025 |
Security changes may require a version upgrade like any other API changes. Avalara can roll out most security as hotfixes (patch version update).
For security fixes, Avalara SDKs will be updated simultaneously with the API, without providing a choice to the customer to update to the newer SDK.
Users can specify a version in one of two locations: in the header or in the request URL. Note that the entire version (n.x.y) must be included in a request.
Specifying a version in the header
The following example shows how to specify version 1.0.0 of the Avalara API in the HTTP header:
POST /service/resource
Host: api.avalara.com
avalara-version: 1.0.0
Content-type: application/json
Specifying a version in the request URL
The same request using a query-string to express version is:
https://api.avalara.com/service/resource?api-version=1.0.0
Note: If both formats are present, the specification in the header takes precedence.
The Avalara service takes into consideration that users may input incorrect versions, and it provides responses for these scenarios:
- version-too-new: If a user passes along a version that's greater than the newest available version, the service will respond with an HTTP 400 (Bad Request) error and indicate in the response that the version is too new.
- version-too-old: If the version is less than the earliest supported version, the service will respond with an HTTP 400 (Bad Request) error and indicate in the response that the version is too old.
- version-not-valid: If a user inputs a version that isn't understood by the service, the service will respond with an HTTP 400 (Bad Request) error and indicate that the version is not valid.
In any of the above cases, the HTTP response will also include a list of supported versions.