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.

Interacting with the API

The following steps walk you through simple interactions with the APIs.

List APIs in your organization

You can begin by listing all of the API proxies in your organization. (Remember to substitute entries for myname:mypass and {org_name}. For instructions, see API reference getting started.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/apis

Sample Response:

[ "weatherapi" ]

Get an API

You can call the GET method on any API proxy in your organization. This call returns a list of all available revisions of the API proxy.

$ curl -u myname:mypass -H "Accept: application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis/weatherapi

Sample Response:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

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 merely 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 deploy an API proxy. This behavior can be overridden in the management UI and in the API.

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.

$ curl -u myname:mypass -H "Accept:application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis/weatherapi/revisions/1

Sample Response

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

These API proxy configuration elements are documented in detail in the API proxy configuration reference.

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

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments

Sample Response

[ "test", "prod" ]
If you have an On-Premise 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.

First undeploy the existing revision. Using query parameters, specify the environment name and the revision number of the API proxy you want to undeploy:

$ curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments"
-u myname:mypass

Then deploy the new revision. (You can deploy using the same revision number, or you can increment it.)

$ curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments" \
-u myname:mypass

Using this approach, there will inevitably be some lag between the time when the first package is undeployed and the next one 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

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.

$ curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments?"override=true" \
-u myname:mypass

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 requets.
  • 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.
  • However, Revision 1 may still be processing existing transactions. By setting the delay parameter (for example, 15 seconds), you give Revision 1 15 seconds to finish processing existing transactions.
  • After the delay interval, Revision 1 is undeployed.
$ curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments?"override=true&delay=15" \
-u myname:mypass
Query Parameter Description
override

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.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/weatherapi/revision/1/deployments \
-u myname:mypass 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

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:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/deployments

This returns the same result as above for every API deployed in the test environment

See all deployments in your organization

To fetch a list of all currently deployed revisions of all API proxies in all environments, use the following API method:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/deployments -u myname:mypass 

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:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

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.

You can also read about these configuration elements in the API proxy configuration reference.

Scripting against the API

The Using the samples, 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

First, make sure the Python deploy tool is available in your local environment.

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.)

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

To make your life really easy, also create a script to invoke and test the API, as follows:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

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.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api
	
source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed. One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST

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:

  1. Centralize credentials in a single file that is used as a source for the programs and scripts that you write
  2. Protect the credentials source file to the extent possible using file system security and permissions
  3. Create an automation client with highly restricted permissions on specific resources in your organization.

Get help

For help, see Apigee Customer Support.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)