You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/deploy/ui-deploy-new). 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](https://apidocs.apigee.com).
To use the Edge API, you must authenticate yourself in your calls. You can do this with
one of the following methods:
- [OAuth2](https://docs.apigee.com/api-platform/system-administration/using-oauth2) (Public Cloud only)
- [SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge) (Public and Private Cloud)
- [Basic Auth](https://docs.apigee.com/api-platform/system-administration/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.
[Video](https://www.youtube.com/watch?v=3BEKp6DrmTo)
## 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](https://docs.apigee.com/api-platform/fundamentals/developing-apigee-edge#usingtherestfulmanagementapi).
```
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
> [!WARNING]
> **Warning:** 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 an API proxy](https://apidocs.apigee.com/docs/api-proxies/1/routes/organizations/%7Borg_name%7D/apis/post) API. If you
don't want to increment an API proxy's revision, use the [Update
API proxy revision](https://apidocs.apigee.com/docs/api-proxies/1/routes/organizations/%7Borg_name%7D/apis/%7Bapi_name%7D/revisions/%7Brevision_number%7D/post) API. If you're using Maven to deploy, use the `clean` or
`update` options, as described in the [Maven plugin
readme](https://github.com/apigee/apigee-deploy-maven-plugin).
> [!IMPORTANT]
> **Best practice:** 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 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](https://docs.apigee.com/api-platform/reference/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.
> [!IMPORTANT]
> **Tip:** 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 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" ]
```
> [!NOTE]
> **Note:** 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 `` element for that environment.
> [!IMPORTANT]
> **Tip:** 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.
> [!IMPORTANT]
> **Best practice:** 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.
You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/deploy/ui-deploy-new). info
> [!NOTE]
> **Note:** 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:
```
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
```
> [!WARNING]
> **Warning:** 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` 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.
> [!NOTE]
> **Note:** 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.
```
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 `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/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"
}
```
> [!IMPORTANT]
> **Tip:** 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](https://docs.apigee.com/api-platform/reference/api-proxy-configuration-reference).
## Scripting against the API
The [Using the sample API proxies](https://docs.apigee.com/api-platform/samples/using-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](https://github.com/apigee/api-platform-samples/tree/master/tools) 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`](https://github.com/apigee/api-platform-samples/tree/master/setup).
```
#!/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](https://github.com/apigee/api-platform-samples/tree/master/setup).)
```
#!/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
```