The API change introduces no new entities versions 1 and 2 simply provide two different "formats" for manipulating the same bank accounts.įurther, any change made using the version 2 API changes the underlying account entity in ways that are visible to clients of the version 1 API. The important point in this example is that version 1 and version 2 of the API both allow access to the same bank accounts.
I don't think there's an API designer who hasn't one day wished they had organized the information in some request or response differently. At some point, the bank sees a way to improve the web API to attract more developers to it they decide to introduce a new version. In addition, the bank has a web API that allows access to accounts programmatically. These accounts have been around for a long time and customers can get information about these accounts through multiple channels (the postal service, the telephone or the bank website, for example). Type 1 versioning: format versioningConsider the example of a bank that maintains accounts for customers. Understanding the two different meanings of API versioning is a prerequisite to deciding how and when to use each. My aim is to bring some clarity and offer unequivocal practical advice.Ī significant part of the confusion around API versioning stems from the fact that the word “versioning” is used to describe at least two fundamentally different techniques, each with different uses and consequences.
Here on the Apigee team at Google Cloud, we design, use and see a lot of APIs, and have developed some strong opinions about the right way to version them. With all this information, who’s an API developer to believe? (For some examples of those divergent views, take a look at this blog post and its bibliography and this interview with the author of the original REST dissertation). There's a lot of advice on the web about API versioning, much of it contradictory and inconclusive: One expert says to put version identifiers in HTTP headers, another expert insists on version identifiers in URL paths, and a third says that versioning of APIs is not necessary at all.
0 kommentar(er)
