API Versioning
How Global Fishing Watch versions its API, how long each major version is supported, and how version changes are communicated.
- Only major versions are tracked, current version is v3
- A new major version is created when there are breaking changes in the endpoints, Request (composed by url, params and verb) and/or the Response
- We only support 2 major versions running at the same time
Communication around API versions
- We send a deprecation notice 3 months in advanced:
- Via email to all registered users
- Via API, by returning a warning message with an url in the log when detecting you are using an old API
- Old API version will live 3 months while new API version is release
| Version | Version Status | Deprecation Date | Release Notes |
|---|---|---|---|
| v3 | 🟢 CURRENT | Release Notes v3 | |
| v2 | 🔴 DEPRECATED | April 30 2024 | Release Notes v2 |
| v1 | 🔴 DEPRECATED | May 31 2023 |
- Version status:
- 🔴 DEPRECATED: The endpoint is not operational or is going to be deleted soon. No improvements are added.
- 🟠 MAINTENANCE: The endpoint is operational and available but marked as in maintenance mode. That means that the engineering team are going to work on fixing issues but not implementing new/update features. All improvements/fixes in this version must has retrocompatibility. Users should plan to start using the CURRENT version.
- 🟢 CURRENT: The endpoint is operation and available to the public users. This version is alive and the engineering team will be able to implementing new features. In case there is a breaking change, a new version should be publish.
- Version deprecation date: when it was or will be deprecated
- Release Notes: What changes are included in the version
For API Dataset Versioning, check here