API versioning within an Apigee environment to support APIs visible on the developer portal

[nmunro]

Hello Community,

I am looking for some feedback and best practice direction on an approach to API versions within a single Edge environment.

We would like to follow a process for release to production that mirrors what we do in areas other than API development.

The process is very simple and nothing out of the ordinary:

• We have 3 environments: prod, qas, and dev.
• When the development passes tests by the developer it is moved to the test environment
• Once in "test" it is tested further by the users/customers
• When it is deemed ready it is then moved to production

We have been discussing how to keep a stable version in the test environment that matches what we have in prod. This is what we'd have visible as a test environment via the dev portal for app developers.

To keep to our process above we would then have another version in the test environment for API versions that need to be tested but are not ready for production.

So, we were thinking of something like:

1. https://basepath/api1/v1/resource (prod)
2. https://basepath/api1/v1/resource?test=true (qas, but matches prod and would change only with new version to prod. This is test version visible on dev portal)
3. https://basepath/qas/api1/v1/resource (qas, new api revision or version under test but not ready for prod)

Is this an approach we should follow or is there a better or simpler way to do this?

What is the most common approach to what app developers use via the dev portal as a sandbox or test environment?

Thanks

Neil

[#2]

Hi @Neil Munro ,

You don't need to have different resource definitions to identify the APIs deployed in various environments .

With the help of Virtualhosts you can route the traffic to a specific environment .

Pls refer virtualhost definition and various properties available here

http://apigee.com/docs/api-services/content/virtual-hosts

[nmunro]

Thanks @Maruti Chand,

I considered virtual hosts - I'm still not sure it works for the situation I described even after re-reading the docs you referenced.

This has helped though because it pushed me to also re-read about route rules - I'm thinking this may be more applicable (in conjunction with virtual hosts).

I'll read the docs again and try to get it clear in my head.

Thanks

[Former Community Member]

So @Neil Munro looks like that you are trying to do things in one environment whereas it seems like they should be 2 separate environments IMO.

One option to consider (for item 2 in the 3 item list you reference above) having a "sandbox" environment

https://api-sandbox.mycompany.net/basepath/.

that is separate from the "qas" environment

https://api-qas.mycompany.net/basepath/.

The sole purpose of this environment would be to mirror the prod environment

https://api.mycompany.net/basepath/.

and provide as a playground for them to test.

As @Maruti Chand mentions you can use virtual hosts to map the endpoints to the different environments.

[gnanasekaran · Accepted solution]

Hi Neil,

Adding to maruti's comments, you typically do not need to create different resource paths for different env, this makes your API inconsistent across env and becomes difficult to test and consume.

Better way to handle this is Virtual Host and Host Aliases, for eg, typically you would have configued 3 different domain names for each of your env,

dev-api.me.com -> dev env

qa-api.me.com -> qa env

api.me.com -> production

all have same set of resource, just different hostname. Its pretty straightforward to setup and many of our customers follow this approach

This way you could map your existing development lifecycle / continous delivery to map to Apigee's environment

"We have been discussing how to keep a stable version in the test environment that matches what we have in prod. This is what we'd have visible as a test environment via the dev portal for app developers." -- Sounds like you need another env, probably 'stage' or 'sandbox' before it goes to production.

In Apigee, Environments are logical, so its easier to setup a new environment without need for additional infrastructure. Plus, it also provides a cleaner way to manage your delivery process.

Thanks,

[nmunro]

@mukundha@apigee.com, @Prithpal Bhogill,

Thanks for your answers.

Separate environments would be the best option but that's not available to us right now. For the first year we will be Edge SMB customers so there are only 3 environments available. Not sure we can do without a dev environment (at least initially).