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
delayparameter (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
| Query Parameter | Description |
|---|---|
override |
Default is Set to |
delay |
To allow transaction processing to complete on the existing revision before it is
undeployed—and eliminate the possibility of Default is 0 (zero) seconds. When |
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 ServicesAPIProxy name: The unique name of the API proxyConfigurationVersion: API Services version to which the API proxy configuration conformsCreatedAt: Time when the API proxy was generated, formatted in UNIX timeCreatedBy: Email address of the Apigee Edge user who created the API proxyDisplayName: A user-friendly name for the API proxyLastModifiedAt: Time when the API proxy was generated, formatted in UNIX timeLastModifiedBy: Email address of the Apigee Edge user who created the API proxyPolicies: A list of policies that have been added to this API proxyProxyEndpoints: A list of named ProxyEndpointsResources: A list of resources (JavaScript, Python, Java, XSLT) available to be executed in this API proxyTargetServers: A list of named TargetServers (that can be created using the management API), used in advanced configurations for load balancing purposesTargetEndpoints: 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