Best Practices of API Versioning.

Hello,

I would like to know what are the best practices for apigee proxy versioning.

Currently we have a proxy which has version in the URI itself like /v1/api. Now we have a requirement to create a version 2 of the same proxy as /v2/api.I would like to know if v2 should be created as a separate proxy with base path /v2/api or should it created as different revision of the same proxy? Since we are using version in the base path hence both the revisions (with v1 and v2) can be deployed in the same environment as there will be no base path conflict.

Kindly let me know what is the Apigee recommended best practices to maintain version and code.

Thanks!

0 7 5,423
7 REPLIES 7

Not applicable

Hi,

Versioning of API vary from organisation to organisation.

But better approach is to maintain at least one version back to give developer atleast one cycle to react before obsoleting version..

You can keep the old version maximum 8-10 months.

/v2/{requestPath} -->is the proper version way.

Yes that should not be issue deploying different version as your base path is different

Thanks @Binaya Kumar lenka . Just another query, whether to have the second version as a separate proxy or as a separate revision? Kindly suggest.

Not applicable

Hi,

I prefer to have the separate version than a separate proxy.

Because separate proxy should have the totally different functionality.

it is better to have separate version in your case.

@Binaya Kumar lenka Thanks for the suggestion.

How do you keep multiple versions (/v1/ and /v2/) deployed to one production environment without creating new proxies?

@Khashayar Parhami you can keep two revision deployed on same API Proxy as shown below with two different version like /v1 and /v2 deployment.png

Technically - We can have one or more versions deployed in an Apigee environment [ Given that the basepaths are different i.e. with /v1,/v2 .../vn ]

However having different versions of the API deployed in an environment depends on API strategy of the organization [the API owner or the API platform owner ].

API platform owner could define general enterprise rules for the APIs to be deployed

e.g. 1. No of active versions (x) in production. Usually we should not go beyond 3-4 active versions.

2. Decommissioned and deprecated API retention period. [ Say 3 Months window -- Allowing consumers of this version to move to the latest version ]

3. Notification/Presentation of these APIs over the API catalog portal.

API owner may decide the road map for the API with some rules in mind. e.g.

1. Having backward compatibility with older versions mainly in terms of the operations.

2. Only the breaking changes may be considered for the version change. For minor change, which may not impact the existing consumers going with the new version may not be required. Only the spec version may change and tracked separately. And the API proxy goes to new revision with the same version : In this case - existing consumers will get auto promoted to the latest spec and latest revision.