Send Docs Feedback

Understanding deployment

This topic provides a quick overview of proxy deployment. You can deploy proxies using the mangement UI, command-line scripts, or with APIs. 

When to deploy a proxy

A proxy must be deployed before it can be invoked. Generally, it's up to you when you deploy. When you are working in a test environment, you may deploy iteratively many times. On the other hand, the decision to deploy a proxy from the test environment to a production environment usually depends on lifecycle rules established by your development team. 

Deploy or redeploy a proxy when you:

  • Create a new proxy (deployment happens automatically)
  • Modify an existing proxy 
  • Create a new revision of  a proxy
  • Create a new version of a proxy
  • Push a proxy from one environment to another, such as from a test environment to a production environment. 
  • Delete and recreate a keystore.

Where to deploy a proxy

You deploy a proxy to an environment. All organizations in Apigee Edge, by default, have two environments called test and prod. These environments are merely designed to provide you with one area to work on and test API changes, and another area where APIs are exposed to apps. The following figure shows a proxy that is deployed to the test environment, as indicated by the green dot. 

Depending on your role, you may not be able to deploy to all environments. Users can only deploy to the test environment. If you're an administrator you can deploy to any environment.

How to deploy a proxy

How you deploy a proxy depends on where you are developing the proxy. If you are working in the UI, you can easily deploy a proxy with just a couple of mouse clicks. A new proxy is automatically deployed when you create it; you don't have to do anything special. The procedure for redeploying an existing proxy is almost as simple. Just select which deployment environment to deploy to, and the management UI takes care of the rest. For more information, see Deploying proxies in the UI.

If you are developing proxies and related components offline (that is, working with proxy XML files and other code directly on your filesystem), Apigee Edge provides a convenient command-line deployment tool that you can use. You can also obtain a sample shell script that you can configure and run to upload and deploy your proxy files. For more information, see Deploying proxies from the command line.

Finally, you can use the Edge management API to deploy proxies. The deployment APIs expose atomic functions that your development team can coordinate to automate and optimize your API development lifecycle. See Deploy API proxies using the management API.

What is an API Proxy Revision?

Revisions let you manage API proxy updates as you create and deploy them to an environment. Revisions are sequentially numbered, enabling you to revert a change by deploying a previous revision of your API proxy. Only one revision of an API proxy can be deployed in an environment at a given time if revisions share the same API proxy base path. However, by changing the base path, you can deploy multiple versions of an API proxy in the same environment. For more information, see Deploying proxies in the UI.

Typically, an existing revision must be undeployed before a new one can be deployed. Other advanced options include overwriting a deployed revision or opting not to increment a revision at all. For example, sometimes when you make minor changes, you might not want to increment the revision. These advanced options can be accomplished through direct calls to the Edge management API. See Deploy API proxies using the management API.

You can deploy a revision of an API proxy into the prod environment, while continuing to create new revisions of that API proxy in the test environment. When you are ready, you can "promote" the higher revision of your API proxy from the test environment over the prior revision of the API proxy in the prod environment.

For more information on revisions, see Deploy API proxies using the management API and Deploying proxies in the UI.

What is an API Version?

While a revision usually represents a relatively minor update, made in the course of a development cycle, the version of an API should change relatively infrequently. Typically, a version reflects a significant change in the signature of an API and requires developers to modify their code accordingly. Versions are usually reflected directly in the API proxy's base URI. For example:


Don't confuse the version of an API (that is, the public interface) with the revision of an API proxy (that is, the internal number associated with a configuration). The two numbers are unrelated, and the revision number of an API proxy is totally opaque to apps that consume your API.

As an API provider, you need to determine when it's appropriate to release a new version of your API, and therefore require developers to migrate their apps to call the new URI.

However, you can keep multiple versions of an API proxy live by deploying them to the same environment with different base paths, which you'd get by using /v1, /v2, /v3, etc. in the base path.

For more information, see the next section, "Versioning best practices."

Versioning best practices

Keep the following best practices in mind when you consider API versioning:

  • Never release an API without a version.
  • Make the version mandatory.
  • Specify the version with a "v" prefix. Place the prefix to the far left in the URL so that it has the highest scope, e.g., /v1/dogs.
  • Use a single ordinal number, such as v1, v2, and so on.
  • Make the version part of the API base path.
  • Maintain at least one version back.
  • Set up a reasonable deprecation policy. Give developers plenty of time and warning before deprecating features. Depending on your developer's platform, that can be six months or two years. For example, mobile apps take longer to rev than web apps.

Do not use the dot notation, like v1.2 for an API proxy version. This implies a granularity of versioning that doesn't work well with APIs.


Help or comments?