Deploy API proxies using the management API

Every organization has a unique software development lifecycle (SDLC). It is often necessary to synchronize and align API proxy deployment with the processes used for backend services.

The Edge management API methods demonstrated in this topic can be used to integrate API proxy management into your organization's SDLC. A common usage of this API is to write scripts or code that deploy API proxies, or that migrate API proxies from one environment to another, as part of a larger automated process that also deploys or migrates other applications.

The management API makes no assumptions about your SDLC (or anyone else's, for that matter). Rather, it exposes atomic functions that can be coordinated by your development team to automate and optimize your API development lifecycle.

All of the management APIs are documented in APIs. This topic focuses on the set of APIs that are for managing API proxies.

The only detail returned by this method is the name of the API proxy along with the associated 'revision', which has an associated number. API proxies consist of a bundle of configuration files. Revisions provide a lightweight mechanism for managing your updates of the configuration as you iterate. Revisions are sequentially numbered, enabling you to revert a change by deploying a previous revision of your API proxy. Also, 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.

In this example, there is only one revision because the API proxy was just created. As an API proxy moves through the lifecycle of iterative configuration and deployment, the revision number increments by integers. Using direct API calls to deploy, you can optionally increment the revision number of the API proxy. Sometimes when you make minor changes, you might not want to increment the revision.

Get API Revision

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.

The API version (for example, api.company.com/v1) should change very infrequently. When you do increment the API version, it signifies to developers that there has been a significant change in the signature of the external interface exposed by the API.

The API proxy revision is an incremented number associated with an API proxy configuration. API Services maintains revisions of your configurations so that you can revert a configuration when something goes wrong. By default, an API proxy's revision is automatically incremented every time you import an API proxy by using the Import a new API Proxy API. If you don't want to increment an API proxy's revision, use the Update API Proxy Revision API. If you're using Maven to deploy, use the clean or update options, as described in the Maven plugin readme.

To obtain the detailed profile of an API proxy configuration, you call the GET method on a specific revision number.

For example, you can call the GET method on API proxy revision 1 to get a detailed view.

Deploying an API to an environment

Once your API proxy is configured to receive and forward requests properly, you can deploy it to one or more environments. Usually, you iterate on API proxies in 'test' and then, when ready, you 'promote' the API proxy revision to 'prod'. Often, you will find that you have many more revisions of an API proxy in the test environment, primarily because you will do much less iteration in the prod environment.

An API proxy cannot be invoked until is has been deployed to an environment. Once you have deployed the API proxy revision to prod, you can then publish the 'prod' URL to external developers.

As you've seen, you deploy the API revision to an environment, so the first step in deploying API proxy revisions is to verify the list of environments in your organization.

How to list environments

Every organization in Apigee Edge has at least two environments: 'test' and 'prod'. The distinction is arbitrary. The goal is to provide you with an area to verify that your API proxy is working properly before you open it up to outside developers.

Each environment is really just a network address, enabling you segregate traffic between the API proxies that you are working on, and those that are being accessed by apps at runtime.

Environments also provide segregation of data and resources. You can for example, set up different caches in test and prod, which can be accessed only by API proxies executing in that environment.

View environments in an organization

If you have an on-premises installation of Apigee Edge, you may see a different list of environments.

Explore Deployments

A "deployment" is a revision of an API proxy that has been deployed in an environment. An API proxy that is in the 'deployed' state is accessible over the network, at the addresses defined in the VirtualHost for that environment.

It is often useful to check to see in which environment (and if!) your API is deployed. For example, you might find requests to your API proxy are failing. One troubleshooting step is to ensure that the API proxy is deployed as expected.

Deploying API proxies

API proxies cannot be invoked until they have been deployed. API Services exposes RESTful APIs that provide control over the deployment process.

The following APIs are called on your behalf by the Python deploy tool. The deploy tool provides support for packaging and importing API proxies that you develop locally, and it also manages undeployment of existing API proxy revisions. Use the direct API calls described below when you need additional control over the deployment process.

Only one revision of an API proxy can be deployed in an environment at a given time. Therefore the deployed revision needs to be undeployed. You can control whether the new bundle is deployed as a new revision or whether it overwrites the existing revision.

The size limit of a proxy bundle is 15 MB.

First undeploy the existing revision. Specify the environment name and the revision number of the API proxy you want to undeploy:

Using this approach, there will inevitably be some lag between the time when the first revision is undeployed and the new revision is deployed. During this interval, calls from apps may be rejected with an HTTP code 5xx. If this is a problem, as it usually is in production deployments, use the seamless deployment option, described below.

Seamless deployment (zero downtime)

To minimize the potential for downtime during deployment, use the override option on the deployment method, and set it to true.

You cannot deploy one revision of an API proxy on top of another. The first must always be undeployed. By setting override to true, you indicate that one revision of an API proxy should be deployed over the currently deployed revision. The result is that the deployment sequence is reversed--the new revision is deployed, and once the deployment is complete, the already deployed revision is undeployed.

You can further optimize deployment by setting the delay parameter. The delay parameter specifies a time interval, in seconds, before which the previous revision should be undeployed. The effect is that in-flight transactions have a time interval in which to complete before the API proxy processing their transaction is undeployed. Following is what occurs with override=true and the delay parameter set:

Revision 1 is handling requests.

Revision 2 is being deployed in parallel.

When Revision 2 is fully deployed, new traffic is sent to Revision 2. No new traffic is sent to Revision 1.

With override set to true, Apigee will not undeploy Revision 1 if the basepath of Revision 1 differs from that of Revision 2. In such a scenario, you will end up having two revisions deployed in the same environment. This can break other plugins and wrappers that make use of the seamless deployment API if you are not accommodating for this scenario in your assertion.

Default is false (normal deployment behavior: existing revision is undeployed, then new revision is deployed).

Set to true to override the normal deployment behavior and provide seamless deployment. The existing revision remains deployed while the new revision is also being deployed. When the new revision is deployed, the old revision is undeployed. Use in conjunction with the delay parameter to control when undeployment occurs.

delay

To allow transaction processing to complete on the existing revision before it is undeployed—and eliminate the possibility of 502 Bad Gateway or 504 Gateway Timeout errors—set this parameter to the number of seconds you want undeployment to be delayed. There is no limit to the number of seconds you can set, and there are no performance ramifications for setting a large number of seconds. During the delay, no new traffic is sent to the old revision.

Default is 0 (zero) seconds. When override is set to true and delay is 0, the existing revision is undeployed immediately after the new revision is deployed. Negative values are treated as 0 (zero) seconds.

When override=true is used along with a delay, HTTP 5xx responses during deployment can be eliminated. This is because both API proxy revisions will be deployed simultaneously, with the older revision undeployed after the delay.

See all deployments of an API Revision

Sometimes it's necessary to fetch a list of all of the currently deployed revisions of an API proxy.

The response above contains many properties specific to the internal infrastructure of Apigee Edge. Unless you are using Apigee Edge on-premise, you can't change these settings.

The important properties contained in the response are organization, environment, aPIProxy, name, and state. By reviewing these property values, you can confirm that a specific revision of an API proxy is deployed in an environment.

See all deployments in the test environment

You can also retrieve the deployment status for a specific environment (including the revision number of the currently deployed API proxy) using the following call:

This returns the same result as above for all API proxies deployed in all environments.

Since the API is RESTful, you can simply use the POST method, along with a JSON or XML payload, against the same resource to create an API proxy.

A profile for your API proxy is generated. The default representation of an API proxy is in JavaScript object notation (JSON). Below is the default JSON response to the POST request above, which created an API proxy called 'weatherapi'. A description of each element in the profile follows:

Keep in mind that the response payload merely contains a representation of an API resource — you can create an API proxy using JSON or XML, and you can also retrieve representations of the API proxy as XML or JSON, depending on your needs.

The API proxy profile that is generated demonstrates the complete structure of an API proxy:

APIProxy revision: The sequentially numbered iteration of the API proxy configuration, as maintained by API Services

APIProxy name: The unique name of the API proxy

ConfigurationVersion: API Services version to which the API proxy configuration conforms

CreatedAt: Time when the API proxy was generated, formatted in UNIX time

CreatedBy: Email address of the Apigee Edge user who created the API proxy

DisplayName: A user-friendly name for the API proxy

LastModifiedAt: Time when the API proxy was generated, formatted in UNIX time

LastModifiedBy: Email address of the Apigee Edge user who created the API proxy

Policies: A list of policies that have been added to this API proxy

ProxyEndpoints: A list of named ProxyEndpoints

Resources: A list of resources (JavaScript, Python, Java, XSLT) available to be executed in this API proxy

TargetServers: A list of named TargetServers (that can be created using the management API), used in advanced configurations for load balancing purposes

TargetEndpoints: A list of named TargetEndpoints

Note that many of the elements of the API proxy configuration created using the simple POST method above are empty. In the following topics, you will learn how to add and configure the key components of an API proxy.

Scripting against the API

The Using the sample API proxies, available on GitHub provide shell scripts that wrap the Apigee deploy tool. If for some reason you cannot use the Python deploy tool, then you can call the API directly. Both approaches are demonstrated in the sample scripts below.

Wrapping the Deploy Tool

Then create a file to hold your credentials. The deployment scripts that you write will import these settings, helping you to centrally manage the credentials for your account. In the API Platform sample, this file is called setenv.sh.

#!/bin/bash
org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"
# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"
export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

The file above makes all of your settings available to the shell scripts that wrap the deploy tool.

Now create a shell script that imports those settings and uses them to call the deploy tool. (You can see an example here.)

Directly invoking the API

It can be useful to write simple shell scripts that automate the process of uploading and deploying API proxies.

The script below directly invokes the management API. It undeploys the existing revision of the API proxy that you are updating, creates a ZIP file from the /apiproxy directory containing your proxy configuration files, and then uploads, imports, and deploys the configuration.

Security guidelines

The Edge management API relies on HTTP Basic Authentication. You need to provide a username and password for each API call.

In some situations, it is not practical to collect the password when the script runs. For example, you may need to run a cron job that fires when no administrators are present. In these situations, you need to make the password available to the script without any human intervention.

Follow these guidelines:

Centralize credentials in a single file that is used as a source for the programs and scripts that you write

Protect the credentials source file to the extent possible using file system security and permissions