Send Docs Feedback

Part 1: Create your API

This tutorial walks you through the process of setting up your first API proxy by using the Apigee Edge management UI.

Alternatively, you can create the API proxy as a set of XML files. Often new users prefer the management UI, but as they gain more experience they migrate to using XML files. For a tutorial on creating the same API proxy in XML, see Part 1: Create your API in XML.

If you're new to 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 Edge, you configure an API proxy for one or more existing services. Under the hood, 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.

  11. Notice that the API proxy is automatically deployed to the 'test' environment. You can select the Deployment drop-down to deploy to the 'prod' environment, if desired.

Learn more

Understanding APIs and API proxies

Step 2: Define a conditional flow for the API proxy

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

A conditional flow is simply a processing path in an API proxy. The API proxy tests for the condition specified in the conditional flow and, if the condition is met, the processing steps in the conditional flow are executed by the API proxy. If the condition is not met, then the processing steps in the conditional flow are bypassed.

Conditional flows are evaluated in the order defined in the API proxy and the first one whose condition is met is executed.  

By defining conditional flows, you gain the ability to apply processing steps in an API proxy based on:

  • Request URI
  • HTTP verb (GET/PUT/POST/DELETE)
  • Value of a query param, header, and form param
  • Many other types of conditions 

In this step, you define a conditional flow for a specific request URI, called the Path, along with the HTTP verb, GET, used to access the API proxy. While you define the conditional flow in this step, you add the processing steps specific to the conditional flow later in the tutorial.

  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. Click the Develop tab in the upper right of the API proxy page.

  4. Click the "+" sign to the right of default under Proxy Endpoints to add a new conditional flow.
  5. In the New Conditional Flow dialog box:
    1. Enter forecast for the Flow Name.
    2. Enter weather conditional flow for the Description.
    3. Select Path and Verb for the Condition Type.  
    4. Enter /forecastrss as the Path.
    5. Choose GET for the Verb.
    6. Leave the Optional Target URL area blank.
    7. Click Add.
  6. Click Save in the upper-left corner to save your changes to the API proxy. Your conditional flow is now added to the proxy:

Notice the XML added to the Proxy Endpoint to define the conditional flow: 

<Flows>
  <Flow name="forecast">
    <Description>weather conditional flow</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/forecastrss") and (request.verb = "GET")</Condition>
  </Flow>
</Flows>

A GET request that matches this condition takes the form:

http://{myorg}-test.apigee.net/v1/weatherxml/forecastrss

You could add another conditional flow to add specific processing steps for a PUT request to the "/forecastrss" resource. For example:

  <Flow name="forecastPUT">
    <Condition>(proxy.pathsuffix MatchesPath "/forecastrss") and (request.verb = "PUT")</Condition>
  </Flow> 

Learn more

Mapping conditional flows to backend 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 API proxy that you want to access. That URL has the form:

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

The URL was automatically generated when you created 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} definition that you specified above when you create the API proxy.
  • The resource path, {resource-path}, of the destination endpoint.

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?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)