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 Build a Proxy wizard, select Reverse proxy (most common), and click Next.
  6. Configure the proxy with the following:
    In this field do this
    Proxy Name Enter: weather
    Project Base Path

    Change to: /v1/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.

    Adding a version number is considered a best practice to version your API. For more information on this important topic, see Versioning Best Practices.

    Existing API

    Enter: http://weather.yahooapis.com

    This defines the target URL that Apigee Edge invokes on a request to the API proxy.

    Description Enter: Yahoo weather proxy

  1. Click Next.
  2. In the Security page, select Pass through (none) as the security option. In later tutorials, we'll show you how to use API Key and OAuth 2.0 security options.
  3. Leave the Browser option unselected, and click Next.
  4. In the Virtual Hosts page, accept the defaults and click Next. If you'd like to learn about virtual hosts, see Virtual hosts.
  5. In the Build page, accept the default Deploy Environment (test) and review your proxy settings.
  6. Click Build and Deploy.
  7. In the Summary page, you see an acknowledgement that your new API proxy was created successfully and deployed to your test environment.


     
  8. Click View the weather proxy in the editor to display the details page for the API proxy.

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 new weather API proxy, click the Develop tab in the upper right of the API proxy page.

  2. In the Navigator pane, click the "+" sign to the right of default under Proxy Endpoints to add a new conditional flow.
  3. In the New Conditional Flow dialog box:
    In this field do this
    Flow Name Enter: forecast
    Description Enter: weather conditional flow
    Condition Type Select: Path and Verb
    Path Enter: /forecastrss
    Verb Select: GET
    Optional Target URL Leave blank.
  4. Click Add.
  5. 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/weather/forecastrss 

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.

Substitute your Apigee organization name for {org-name} in the following:

In a web browser http://{org-name}-test.apigee.net/v1/weather/forecastrss?w=12797282
With cURL in a terminal window curl http://{org-name}-test.apigee.net/v1/weather/forecastrss?w=12797282

For example:

curl 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>
     .
     .
     .
      <yweather:forecast day="Wed" date="6 Jan 2016" low="42" high="57" text="Showers" code="11"/>
      <yweather:forecast day="Thu" date="7 Jan 2016" low="42" high="58" text="AM Clouds/PM Sun" code="30"/>
      <yweather:forecast day="Fri" date="8 Jan 2016" low="46" high="59" text="Partly Cloudy" code="30"/>
      <yweather:forecast day="Sat" date="9 Jan 2016" low="41" high="58" text="AM Showers" code="39"/>
      <yweather:forecast day="Sun" date="10 Jan 2016" low="46" high="59" text="AM Clouds/PM Sun" code="30"/>
      <guid isPermaLink="false">USCA1093_2016_01_10_7_00_PST</guid>
    </item>
  </channel>
</rss>

You have successfully added an API to Apigee Edge.

The URL has the following 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}, which you can find in the upper right of the management UI. The organiation 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.

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?