What isn't API Versioning?
It is NOT an indicator of the current release version.
Consumers don't care what your internal software release is. This information doesn't help a consumer build or maintain APIs
What IS API Versioning? Versioning is how you communicate when existing software is likely to break because of an update. Versioning only needs to happen when new required fields are added to queries, OR previously available data are removed from payloads
The Implications
● Versioning happens infrequently
● Versioning is a very impactful change, and may cause breakage of software that you were unaware even existed
● Communications about versioning should be proactive and complete
Best Practice: Avoid making breaking changes. Changes made to an API that will cause downstream breakage will reduce the utility of your API. Reduction in utility will reduce usage and increase time to market, as well as increase the cost associated with updates. Reduction in utility will also reduce use, which impacts value directly when clients pay for usage or indirectly when the organization can't easily leverage the solution.
Pick something and be consistent! Consistency leads to predictability. Predictability leads to intuitive usability. Usability leads to usage. Usage leads to innovation
It is NOT an indicator of the current release version.
Consumers don't care what your internal software release is. This information doesn't help a consumer build or maintain APIs
What IS API Versioning? Versioning is how you communicate when existing software is likely to break because of an update. Versioning only needs to happen when new required fields are added to queries, OR previously available data are removed from payloads
The Implications
● Versioning happens infrequently
● Versioning is a very impactful change, and may cause breakage of software that you were unaware even existed
● Communications about versioning should be proactive and complete
Best Practice: Avoid making breaking changes. Changes made to an API that will cause downstream breakage will reduce the utility of your API. Reduction in utility will reduce usage and increase time to market, as well as increase the cost associated with updates. Reduction in utility will also reduce use, which impacts value directly when clients pay for usage or indirectly when the organization can't easily leverage the solution.
Pick something and be consistent! Consistency leads to predictability. Predictability leads to intuitive usability. Usability leads to usage. Usage leads to innovation
ليست هناك تعليقات:
إرسال تعليق