Was this Helpful?

This tutorial walks you through the process of setting up your first API proxy.

If you're brand new to Apigee Edge, you may want to review What is Apigee Edge? If you're new to RESTful APIs you may want to review this blog post for some background. 

About creating an API proxy and defining API resources

To create an API on Apigee Edge, you configure an API proxy for one or more existing services. Under the hood, Apigee Edge generates a new API, with its own unique network address and processing pipeline, that handles request and response messages. The API is exposed over the Internet and can be invoked over HTTP. 

The API proxy can be as simple or as detailed as you like. For example, an API proxy can be a simple 'passthrough', exposing a single API method and funneling any type of request to a particular backend service. It can also be extremely granular, specifying responses based on the HTTP verb of the request, the URI requested, the content of the request or response, and so on. 

About the Yahoo Weather API

In this tutorial, you will create an API proxy for the Yahoo Weather API. The Yahoo Weather API returns XML-formatted weather reports based on an identifier called a WOEID (Where On Earth ID). The WOEID for Palo Alto, CA is 12797282. You can call this API directly. In a Web browser, enter:

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

The result is an XML-formatted weather report. 

Step 1: Create an API proxy for the Yahoo Weather API

Now go through the steps to send a request to the Yahoo Weather API via an API proxy on Apigee Edge. First create the API proxy:

  1. Login to https://enterprise.apigee.com. (You can obtain a free account at https://accounts.apigee.com/accounts/sign_up.)
  2. If this is the first time that you have logged in, you will land on the Dashboard page. Select the Activate button under API Management. The activation process can take a few minutes.
  3. In the API Platform UI, select the APIs tab.

    APIs tab_0.png

    You will see two existing API Proxies: oauth and weatherapi. Ignore those for now. They are for use in the tutorial Part 1: Deploy OAuth token endpoint.
     
  4. Click the add (+) API Proxy button.


  5. In the "Choose Your Starting Point" section of the New API Proxy dialog box, select Backend Service and enter http://weather.yahooapis.com as the Backend Service URL.

    The Backend Service URL defines the target URL that Apigee Edge invokes on a request to the API proxy.
  6. In the "Identify Your API Proxy" section, enter weather for the Display Name and Yahoo weather proxy as the Description.

    The Project Base Path is automatically set to /weather. The Project Base Path is part of the URL used to make requests to your API. Apigee Edge uses the URL to match and route incoming requests to the proper API proxy.
  7. Add a version number /v1 to the Project Base Path. This step is optional; however, it's considered a best practice to version your API. For more information on this important topic, see "Versioning Best Practices". The path now looks like this:

    /v1/weather
  8. Leave the "Add Features" section as is.


     
  9. Click Build.

    In response, you should see an acknowledgement that your new API proxy was successfully created and deployed into your test environment and listed in the API summary page.

  10. Click Close in the acknowledgement to display the details page for the API proxy.

Learn more

Understanding APIs and API proxies

Step 2: Define a resource for the API proxy

Now you're ready to define your first resource. Defining resources for an API proxy is optional. However, by defining resources, you gain more granular control over the API.

A resource is a simply a URI. By defining specific resources, you gain the ability to apply policies to specific URIs, as well as operational visibility into the performance or consumption of those URIs. You can even further refine resource definitions by specifying the HTTP verb used against the URI.

In this step, you define a resource that represents a weather forecast, along with the verb GET used to access the resource.

  1. In the main menu of the management UI, click APIs to display the API Proxies page. If the API Platform page is not open, click here. Or, navigate directly to the page like this:
    1. Go to www.apigee.com.
    2. Sign in.
    3. Click API Management on the landing page. 
    4. From the APIs menu, select API Proxies
  2. Click weather in the API Proxies table.
  3. In the Resources section of the weather details page, click the + Resource button.
  4. Enter forecast for the Name.
  5. Click the Proxy Endpoint menu and choose default.
  6. Click the Verb menu and choose GET.
  7. Enter /forecastrss as the resource Path. By defining this URI, you can monitor and manage the resource separately from other resources associated with this API proxy.

  8. Click the check icon in the Actions column to add the resource to the API proxy. Notice that the URL column of the table now shows the full URL of the resource. You will use that URL in the next section to make a request.
  9. Click Save.

Learn more

API resources

Step 3: Request the Yahoo Weather API by using your Edge API proxy

Now that you have an API proxy for the Yahoo Weather API, you can make requests to it through Apigee Edge. The first thing you need to determine is the complete URL of the resource of the API proxy that you want to access. That URL has the form:

http://{org-name}-{env-name}.apigee.net/{project-base-path}/{resource-name}?{query-params}

The URL was automatically generated when you added the resource to the API proxy based on your organization and environment, where:

  • Your organization, {org-name}, is typically synonymous with the API project name you provided when you signed up for an Apigee account. Although you can join more than one organization, most users will have an account in only one organization.
  • An environment, {env-name}, provides a runtime execution context for APIs. By default, Apigee organizations are provisioned with two environments: 'test' and 'prod'. When you created the API proxy above, it was automatically deployed to the 'test' environment.
  • The Project Base Path, {project-base-path}, and resource, {resource-name}, definitions that you specified above when you create the API proxy.

In your Web browser, enter the following, substituting your Apigee organization name for {org-name}:

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

For example:

http://myorg-test.apigee.net/v1/weather/forecastrss?w=12797282

Look for the following content in the response: 

<rss xmlns:yweather="http://xml.weather.yahoo.com/ns/rss/1.0" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" version="2.0">
  <channel>
    <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>

You have successfully added an API to Apigee Edge.

Step 4: Where to next?

Now that you have an API defined on Edge, you can make it more powerful by adding policies. Policies let you enhance your API to control traffic, enhance performance, enforce security, and increase the utility of your APIs, without requiring you to write any code or to modify any backend services.

Continue on to Part 2: Add policies to your API to add policies to your API.

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