Deploy API proxies using the API

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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

For complete information, see Edge APIs.

To use the Edge API, you must authenticate yourself in your calls. You can do this with one of the following methods:

• OAuth2 (Public Cloud only)
• SAML (Public and Private Cloud)
• Basic Auth (not recommended; Public and Private Cloud)

This topic focuses on the set of APIs that are for managing API proxies.

Video: Check out this short video to learn how to deploy an API.

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 EMAIL:PASSWORD and ORG_NAME. For instructions, see Use the Edge API.

curl -u EMAIL:PASSWORD \
  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 EMAIL:PASSWORD -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

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

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

curl -u EMAIL:PASSWORD -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 it 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.

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 to 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 EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Sample Response

[ "test", "prod" ]

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> element for that environment.

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.

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.

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

First undeploy the existing revision. 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 EMAIL:PASSWORD

Then deploy the new revision. The new revision of the API proxy must already exist:

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 EMAIL:PASSWORD

Seamless deployment (zero downtime)

To minimize the potential for downtime during deployment, use the override parameter 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.

The following example sets the override value by passing it as a form parameter:

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

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.
• 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/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD

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/revisions/1/deployments \
  -u EMAIL:PASSWORD

{
  "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 EMAIL:PASSWORD
  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 EMAIL:PASSWORD

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"
}

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

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. (For an example see Apigee API platform samples.)

#!/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