Configure and deploy an API proxy

Apigee API proxies are implemented as 'bundles' of configuration files, including policies, and (optionally) custom scripts and code. The configurations files define a processing pipeline for requests and responses that flow from clients apps to 'backend services'.

A backend service in this context refers to any Web service or API that exposed over HTTP. Often, a single API proxy invokes more than one backend service. API proxies are useful for implementing intermediary services that compose data and capabilities from multiple sources to expose innovative and unified APIs to app developers, without requiring development teams to modify any application code.

For developers, one great benefit of the API Platform is its ability to manage APIs that are not necessarily under your control. As you will see in the Developer Guide topics, you can build API proxies that modify the behavior of publicly available APIs. The topics and associated API Platform samples demonstrate interactions with Yahoo weather APIs, Google geocoding and elevation APIs, Twitter, and Microsoft Azure's translation API.

This means that if an API does not meet your requirements, you can build a proxied version of the API that does. For example, if an API only returns XML, but you require JSON, you can simply build an API proxy that performs the conversion. You then build your apps to invoke the proxied URL instead of directly calling the provider's API. You can also share this URL with fellow developers and become an API provider yourself.

You can create and develop API proxies using the Management UI, or using development tools on your local machine. API proxies developed locally can be imported and deployed on the API Platform for runtime testing and production.

Developing API proxies is an iterative process. You should plan to modify, deploy, and test API proxies frequently as you go along. Apigee provides tools to assist in this process.

Creating an API proxy

In the following steps, you create a simple API proxy that acts as a facade to the Yahoo Weather API. You will first directly invoke the Yahoo Weather API. Then you will import and deploy a simple API proxy that is provided as a sample on Github.

Step 1: Invoke the Weather API directly

In this example, you create an API proxy for Yahoo's Weather API.

Begin by invoking the API directly:

$ curl http://weather.yahooapis.com/forecastrss?w=12797282

Sample Response

<title>Yahoo! Weather - Palo Alto, CA</title>
<link>http://us.rd.yahoo.com/dailynews/rss/weather/Palo_Alto__CA/*http://weather.yahoo.com/forecast/USCA1093_f.html</link><description>Yahoo! Weather for Palo Alto, CA</description>
<language>en-us</language>
<lastBuildDate>Wed, 08 Aug 2012 9:47 am PDT</lastBuildDate>
<ttl>60</ttl>
<yweather:location city="Palo Alto" region="CA"   country="United States"/>
<yweather:units temperature="F" distance="mi" pressure="in" speed="mph"/>
<yweather:wind chill="66"   direction="10"   speed="8" />
<yweather:atmosphere humidity="73"  visibility=""  pressure="30.02"  rising="0" />
<yweather:astronomy sunrise="6:18 am"   sunset="8:08 pm"/>

This step refers to the simpleProxy available in the API Platform samples distribution. Refer to API Platform samples for details and downloading instructions.

The simpleProxy is the most basic API proxy supported on the API Platform. It defines:

• A name for the API: weatherapi
• A target URL: http://weather.yahooapis.com (which the API platform uses to consume the Yahoo Weather API)
• A proxy URL: weather (which client apps use to consume your API)

Such API proxies are commonly referred to as "passthrough" proxies, since they merely forward requests and return responses without manipulating them.

If you have not done so, download the API platform samples:

$ git clone https://github.com/apigee/api-platform-samples.git

Navigate to the distribution contents:

$ cd api-platform-samples

Under api-platform-samples note the directory called simpleProxy.

$ cd simpleProxy

Under simpleProxy note the directory called apiproxy.

The apiproxy directory contains the complete, fully functional definition of an API proxy. API proxy configuration files are always stored under a directory call apiproxy, and they define a directory structure that you must use in all API proxies.

You don't need this level of detail to get up and running, but keep in mind that you can always refer to the API proxy configuration reference for an explanation of configuration elements.

For now, you can explore the configuration files to get a sense of what makes up an API proxy. (You don't need to change anything for the sample to work.)

Deploying an API proxy

You have several options for importing and deploying API proxies to your organization on the API Platform:

• The 'Upload Revision' feature in the API detail view of the Management UI.
• A direct API call to the RESTful API exposed by the API Platform. See Import an API.
• The Apigee Python deploy tool
• A shell script that calls the Apigee Python deploy tool (deploy.sh)

Note that the Apigee Python deploy tool calls the RESTful API exposed by the API platform. The deploy tool provides some important ease-of-use functions to make your life easier as you iteratively develop API proxies. It creates a valid ZIP file, performs some simple revision management, and deploys your API proxy to an environment--all in one step.

For the paths in the command below to work, the deploy tool must be run from the base directory in the API Platform samples distribution. You provide a pointer to the directory that contains the /apiproxy directory, in this case simpleProxy.

Note: The -d flag must point to the directory that contains the apiproxy directory.

Substitute your username, password, and Apigee organization in the following command for myname:mypass and myorg.

For example, from the base directory of api-platform-samples, run:

$ python tools/deploy.py -n weatherapi -u myname:mypass -o myorg -e test -p / -d simpleProxy

This single action zips your files, pushes them to your organization on Apigee, and deploys them to the specified environment.

On success you see:

Writing ./simpleProxy/apiproxy/weatherapi.xml to apiproxy/weatherapi.xml
Writing ./simpleProxy/apiproxy/proxies/default.xml to apiproxy/proxies/default.xml
Writing ./simpleProxy/apiproxy/targets/default.xml to apiproxy/targets/default.xml
Imported new proxy version 1
Environment: test
  Revision: 1 BasePath = /
  State: deployed

The tool has zipped up your files, imported the package to Apigee, and deployed to the 'test' environment in your Apigee organization.

Your API is ready to be invoked.

Invoking an API proxy

After you deploy an API proxy to the API Platform, it can be invoked over the network. A set of URLs is created for each environment in your organization. The URLs are defined in a VirtualHost definition file that is stored in the environment. The default URL includes your organization name combined with the environment name and an Apigee-specific domain.

The proxied URL consists of:

• Organization name: The name of the organization in which you have an account on the API Platform
• The environment name: The name of the environment where you want run the API proxy (usually either 'test' or 'prod')
• The Apigee proxy base URL (apigee.net, NOT api.enterprise.apigee.com)
• The base path URI fragment you configure for the API proxy (in the example above, /weather)

The URL for the API proxy in this example is:

http://{org_name}-test.apigee.net/weather

For an organization called 'apifactory', the API proxy address is:

http://apifactory-test.apigee.net/weather

This is the address that you use to call the API at runtime. For example, if you are building an app, you configure the app to call this URL.

So to invoke an API proxy with a complete functional request, clients submit requests to:

$ curl http://{org_name}-{env_name}.apigee.net/weather/forecastrss?w=12797282

The API Platform takes the URI path following the base path (defined in the ProxyEndpoint) and appends the value to the URL defined in the HTTPConnection for the TargetEndpoint. This results in an outbound call to the backend service:

http://weather.yahooapis.com/forecastrss?w=12797282

The API Platform receives the response and returns the response to the client app.

Substitute your organization name for {org_name} in the request below:

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

You can also paste the following into a Web browser:

http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Sample Response

<title>Yahoo! Weather - Palo Alto, CA</title>
<link>http://us.rd.yahoo.com/dailynews/rss/weather/Palo_Alto__CA/*http://weather.yahoo.com/forecast/USCA1093_f.html</link><description>Yahoo! Weather for Palo Alto, CA</description>
<language>en-us</language>
<lastBuildDate>Wed, 08 Aug 2012 9:47 am PDT</lastBuildDate>
<ttl>60</ttl>
<yweather:location city="Palo Alto" region="CA"   country="United States"/>
<yweather:units temperature="F" distance="mi" pressure="in" speed="mph"/>
<yweather:wind chill="66"   direction="10"   speed="8" />
<yweather:atmosphere humidity="73"  visibility=""  pressure="30.02"  rising="0" />
<yweather:astronomy sunrise="6:18 am"   sunset="8:08 pm"/>

Post questions to the Apigee Developer Forum.

Back to API Platform Developer Guide.