API version deprecation policy
How long do API versions live?
Every API version that is exactly two years old or older, will normally be deprecated.
An API version enters its deprecation
pending phase one and a half year after its release and six
months before its canonical deprecation.
It is possible that a version which is older than two years is still active at some point.
This API version is still pending deprecation and its usage is strongly discouraged.
What happens to requests directed to deprecated API versions?
Requests to deprecated API versions are currently being served by version 20200803.
Requests to deprecated versions will return results from a newer version. This version is currently 20200803. The serving version is generally chosen to be as close to the deprecated version as possible. This is to minimize changes in object IDs (see section for differences in data between versions.) These requests should normally return valid (and more up-to-date) results (see section for fresh api versions.)
Thus, for example, if someone using your app does not update it on her device in time, she will continue to normally get valid (and better) results.
Requests to deprecated API versions are not being redirected. It is simply that results from an available version are returned. This is to avoid failing to serve clients that do not follow redirects. Instead an extra field is returned in the response (see the relevant section for deprecation status extra fields.)
How do I know when I am using a deprecated API version?
You should normally expect an API version deprecation every two years since its initial release date. This date is the version's name encoded in ISO format. So for example, a version named
19700101would normally be deprecated on the 1st of January, 1972.
See the relevant section for detailed API version deprecation status.
If you still for any reason do not manage to update in time, once a version is deprecated, all API requests to that version will be served by a newer version, with an extra field indicating deprecation.
Deprecation status extra field
Every API request returns an
is_deprecated field, that has three possible values:
yes: The version is deprecated. Returned results are from a newer supported version (currently 20200803).
pending: The version is still supported but is pending deprecation within six months or less from the time of the request. You should consider switching to a newer version.
no: The version that you are using is not deprecated or pending deprecation.
Observe for example, the value of the field
is_deprecated for a request to a deprecated version:
Also notice that everything else is actually identical to the response for version