Understand Switch API version numbers, maturity labels, compatibility expectations, and how likely APIs are to change.
Use Switch API version numbers and maturity labels to understand API compatibility and how likely a resource or field is to change.
Review this page when you evaluate a new endpoint, field, or workflow for production use, especially if the API contract has an Alpha, Beta, or Gamma maturity label. If you are choosing where to start, see Getting Started.
Version numbers
The Arcadia Switch APIs are version 1.0. There is not currently a version 2.0 or 1.1.
When a new version is introduced, the API signature will allow you to switch between versions. You will not be forced to migrate to a new version for a significant time after it is introduced.
Version names
Within an API version, data structures, operations, and resources can have version names that indicate maturity and how likely the item is to change.
Arcadia makes APIs available early when possible, but maturity labels help you understand the stability of each API contract.
| Version name | Meaning | Change expectation |
|---|---|---|
| Alpha | Early API contract that is still being finalized. | Likely to change. |
| Beta | API contract that has been used in production and has stabilized. | Unlikely to change. |
| Gamma | Field-proven API contract with no anticipated changes. | Very unlikely to change except for low-impact additions. |
Alpha
An alpha designation means Arcadia has defined the expected data definition, operation parameters, and requirements, but the API contract has not been finalized. Alpha APIs are likely to change.
Beta
A beta designation means the API has been used in production and the contract has stabilized. Arcadia tries not to change the contract of an API once it reaches beta.
Gamma
Anything with a gamma label has been field-proven and has no anticipated changes. Gamma APIs are treated as effectively immutable.
If a gamma API changes, the change should be low impact, such as adding a new optional request parameter. Major changes would result in a new version of the API.
Next steps
- Review Requests for compatibility-safe request patterns, including field sets and pagination.
- Review Responses to understand how clients should handle newly added response fields.
- Return to Getting Started to choose the API family that matches your workflow.