The Genability APIs are version 1.0. We do not yet have a version 2.0 (or 1.1). When we do, the API signature will allow you to switch between version. You will not be forced to migrate to a new version for a significant time after it is introduced. We know how difficult it is to find the time to upgrade. We wouldn’t put you through that.
Within a version (i.e within version 1.0), the various data structures and operations/resources have their own version name that highlights the maturity and “changeability” of that item. Genability strives to get our data and APIs out for you to use early and often, but in doing that we want to be careful to not pull the rug out from under you. Here are some guidelines on what each version name means:
An “alpha” designation means that we have done our best to anticipate the required basic data definition and operation parameters and requirements, but the API contract has yet to be finalized and will likely change.
A “beta” designation means that the API has been used in production for a while and the contract has stabilized. We try very hard not to change the contract of an API once it reaches the beta stage.
Anything with a “gamma” label has been field proven, and does not have any anticipated changes coming. It is for all intents and purposes immutable and it will be extremely unlikely that it will undergo any changes. If any changes do occur, they will be very low impact (like adding a new optional parameter to a request). Any major changes needed would result in a new version of the API.