Hello Community
I would like to know what is recommended way of taking backup of any API in API Gateway (v 10.11) before making any changes to the API.
This is required to ensure that we have complete backup of last stable version of any API before we attempt to modify/update it in any way
I would appreciate if I can get community recommendations or expert opinion in this regard.
Should I try to ‘export’ API to take backup?
Should I backup API under new version number? (example: if I am going to update v1.0 of API and I want to take backup then I may use ‘create new version’ option in API Gateway to create v1.1 (as backup copy) and then modify v1.0?
Or is there any better/different approach anyone in community would like to suggest me?
Hi @Mubarik ,
Definitely we can export the assets from the platform and import in future when required.
But in future while importing the assets we need to sure that API GW platform version is same.
Take a scenario you have upgraded the platform version after taking export, then it will be version mismatch issue.
Secondly it would be nightmare to maintain the multiple version of multiple API’s on your laptop disk.
I would prefer to have versioning of API on the platform . With this approach it will not help you to maintain it but also helps you to compare what changes you have don in each version of API.
Hello @Vikash_Sharma1
Thanks for your response. I appreciate. You mentioned you would prefer to have versioning of API on platform.
Can you please further elaborate what do you mean by enabling versioning of API on platform?
I know we can create a new version of an existing API in gateway (by using create new version option). So do you mean manually creating new version of API for changes (and keeping old version as backup)? or is there some configuration / settings at API gateway level, that you are refereeing to and that may enable some implicit/automatic versioning for APIs in gateway?
Wording what @Vikash_Sharma1 shared a bit differently – you never change an existing API that has been published. You “version” it using the API GW versioning facility. Effectively, create a copy with a new version number and make changes to that. Then you have both available.
There are many challenges with such an approach, but that’s a different topic. (API versioning is a huge topic with lots of opinions about what is the “right” way.)
Thanks @reamon for your valuable feedback. I appreciate. I understand the approach you suggested where we can create a new version of an existing API and then make changes to newer version. This approach is clear to me now thanks.
However, I would like to know how can we keep version change transparent to the API consumer? I mean, if I don’t want API consumer(s) come to know that I have created a newer version then how can I seamlessly point that consumer to newer version (instead of older version)?
I am asking it because sometimes it is really difficult for consumer to modify API endpoint/url in their systems and they may prefer to keep using already shared endpoint despite API version changes. So in any such situation what could be a good approach of keeping API versioning transparent to consumer? Should we try to use custom endpoints instead of gateway endpoints as a solution? or would you or other community folks may like to suggest some other/better approach?
You may be able to use URL aliases to good effect. Define an alias for a given API for a given version. Then as you add versions you update the alias to refer to the latest. As long as an API version is non-breaking, the version is not something the API clients see.
Many approaches and pros/cons to consider.
A primary principle that I think everyone should strive for – never break an existing API. Don’t change anything that would cause API client code to stop functioning properly. In general, this means only non-breaking changes Many websites with the same info on this subject.
And some sites have details about how they manage introducing breaking/major changes.
One item I’d add is don’t worry about the “RESTfulness” of any of the guidelines/principles. In one view of the world, including in a comment from Roy Fielding, there is no such thing as “REST API”. Some folks will purport that one approach is more “RESTful” than another but in the majority of the cases the item has nothing to do with REST principles at all. The main thing when considering a particular approach/practice is “does it work for me”. Don’t adopt something simply because someone claims it is “RESTful.”
Last parting thought: if you have an API that is constantly changing which is prompting the “how to manage versions” item, it may be time to re-analyze the API definition to try to get to something that is relatively stable. The API should hide lots of implementation details and change relatively infrequently. Adding elements to an underlying object should not cause API turmoil.
