What's here

This tutorial walks you through the process of setting up APIs with resources, and adding and configuring policies. You'll then add an API product for your API so you can distribute it to your developers.

If you're brand new to the product, 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. 

Step 1: Add an API and define API resources

When you add an API to 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 a processing pipeline that handles request and response messages.  The API is exposed over the Internet and can be invoked over HTTP by client apps. 

The API created can be as simple or as detailed as you like. An API 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. 

Add the Yahoo Weather API

In this tutorial, you will create a 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. 

Now you will go through the steps required to send the same request, and receive the same response, via an API proxy on Apigee Edge.

You must first add the Yahoo Weather API:

  1. Login to https://enterprise.apigee.com. (You can obtain a free account at https://accounts.apigee.com/accounts/sign_up.) 
     
  2. If you land on the Dashboard page, select the Open Platform button in the API Platform box.
  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 Secure calls to your API through OAuth 2.0: Client Credentials.
     
  4. Click the add (+) API Proxy button.



     

  5. In the "Choose Your Starting Point" section of the New API Proxy page, select Existing 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 behalf of apps. You can add any URL that is accessible over the open Internet.
     
  6. In the "Identify Your API Proxy" section, enter weather for the Display Name and Yahoo weather proxy as the description.
     
  7. The Project Base Path is automatically set to /weather.
    The Project Base Path is embedded in the proxy URL that apps call to invoke your API. Apigee Edge uses the proxy URL to match and route incoming request messages to the proper API proxy.

    The base of the API URL is automatically generated based on your organization and environment. Your organization 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 provides a runtime execution context for APIs. By default, Apigee organizations are provisioned with two environments: 'test' and 'prod'.

    For example, if your account is in the organization called apifactory, and your API is configured in the environment test, then the URL that you share with developers would be:

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

  8. 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
     
  9. Leave the "Add Features" section as is.


     
  10. Click Build.

  11. In response, you should see an acknowledgement that your new API proxy was successfully created and deployed. Apigee Edge generates and deploys a set of configuration files that govern the behavior of the processing pipeline for this API proxy as Revision 1. Your new API is automatically deployed into your test environment and listed in the API summary page.
     
  12. Click Close in the acknowledgement to display the details page for the API proxy.

Define API resources

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

An API resource is 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 example, you define a resource that represents a weather forecast, along with the verb GET.

  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.
  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.

  8. Click the check icon in the Actions column.

    The resource is added to the API proxy.

  9. Click Save.

Call the Yahoo Weather API by using your new Apigee API proxy

Now that you have a proxy for the Yahoo Weather API, you can invoke it indirectly through Apigee Edge. 

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: 

<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 added an API to Apigee Edge. You now have the ability modify the characteristics and behavior of the API. In the next step you'll add policies to configure your new API. 

Learn more

Understanding APIs and API proxies

Step 2: Add policies to your API

To design and customize the behavior of your APIs, you apply a set of policies. Each policy performs one of several API management tasks. For example, you can add policies for response caching, rate limiting, XML-to-JSON transformation, and so on.

You can add policies using the API Proxy Editor. The API Proxy Editor lets you see the structure of your API proxy and configure its flow. The editor presents a visual representation of your proxy's message flows as well as an editable display of the XML that defines the proxy.

When you add a policy, you specify the Flow that defines when the policy is executed. Each request and response path in a ProxyEndpoint and TargetEndpoint defines the following Flow types:

  • PreFlow: Always executes before any other Flows. The processing steps defined in the PreFlow are applied to every message that passes through an Endpoint. 
  • Conditional Flows:  Execute only when a conditional statement defined for the Flow evaluates to true. An Endpoint may define any number of conditional Flows, but only the first conditional Flow whose condition evaluates to true will execute. 
  • PostFlow: Always executes after all other Flows. As with PreFlow, the processing defined for PostFlow is applied to every message.

Set a rate limit for your API

To help you learn how to configure APIs, you're going to add the Spike Arrest policy to protect your backend from high traffic. The Spike Arrest policy prevents traffic spikes (or bursts) that can be caused by an increase in usage, buggy clients, or malicious attacks. When the number of requests exceeds the rate limit, the API returns an HTTP 500 error for a request.

  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.
  2. Click weather in the API Proxies table.
  3. On the weather detail page, click the Develop button to open the API Proxy Editor.

  4. In the API Proxy Editor, click New Policy. This displays a categorized list of all the policies you can create.

  5. Select Spike Arrest in the Traffic Management category.

    The New Policy dialog appears showing:

    • The Policy name assigned to the new policy.
    • An Attach Policy checkbox. Checking this box attaches the policy to the Flow.
    • A Flow drop-down menu.
    • Segment request and response radio buttons.
       
  6. Click Add to accept the defaults.

    The new policy is attached to the PreFlow flow of the request message. This means that Apigee Edge will include the Spike Arrest policy as part of its processing of messages sent from a client app to your API. Because you accepted the default selections for the Flow and Segment options, the Spike Arrest policy is applied to request messages at the ProxyEndpoint.

    Learn about flows and endpoints in Understanding APIs and API proxies. What’s important to understand at this point is that the Spike Arrest policy will be processed first by your API proxy.

  7. Ensure that the PreFlow flow is selected in the left side of the API Proxy Editor.
  8. Select the Spike Arrest policy and examine what’s been added:

    • The policy is added to the list of policies in the Navigator view in the upper left of the API Proxy Editor.
    • The policy is added to the Designer view in the top center of the API Proxy Editor, which is a visual representation of your proxy's message flows. Note that the icon appears only when you select PreFlow under Proxy Endpoints in the left navigation area.
    • The XML for the policy is displayed in the Code view in the bottom center of the API Proxy Editor.
    • The XML element and attribute values for the policy are displayed in the Property Inspector at the right in the API Proxy Editor.
       
  9. In the XML for the policy, change the value of the <Rate> element to 75ps. You can specify the rate as an integer value per minute (pm) or per second (ps).

    This limits traffic to a maximum of 75 messages per second. Notice that the Rate value in the Property Inspector also changes to 75ps. You can also change the Rate value in the Property Inspector and it will be reflected in the XML view.

  10. Click Save to save the current revision with your changes.

Learn more

Understanding APIs and API proxies

Step 3: Execute and Trace API calls

The Trace feature lets you review data on how a message changes as policies are executed. You can see how each policy is performing and how long it takes to execute. By examining the data, you can see exactly where things are breaking down. Trace shows you data from a number of calls taken from live data. However, since the weather API is not live you'll send calls manually so you can see how policies are being executed.

  1. In the management UI, click the APIs tab. If the API Platform page is not open, click here.

  2. Click weather in the API Proxies table.
  3. On the weather detail page, click the Trace button to access the Trace page.
  4. On the Trace page, choose the test environment. This will let you set up a trace session on the test environment.
  5. Click Start Trace Session.

    This runs a trace session for 10 minutes. While the trace session is running, messages are captured from live traffic. However, since your API has not be exposed to developers yet, you won't have any traffic.

  6. Request your API.

    You can request your API directly from a Web browser by entering the following URL:

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

    where:

    • {org-name} is the name of your organization
    • {env} is the environment, which is either test or prod. For this tutorial, you deployed the API Proxy to the test environment.

    For example:

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

    Or, request the URL from the Trace page by entering the URL and clicking Send in the Send Requests section.

    You can click Send multiple times to generate as much traffic as you wish.

    You can also use the Apigee Console to send a message directly to your API. The API Console lets you examine the request and response objects, set request headers, and set body parameters. To send the request from the console:

    • Click Send with the Apigee Console, just below the Send button in the Send Requests area of the Trace page.
      The console appears in another browser window.
    • Enter the URL of your API.
    • Click Send.
      This sends a call to your API. You can click send multiple times to generate as much traffic as you wish.
    • Switch back to the trace session.

    The processing time for each message appears in the Transactions section of the Trace page.

  7. Click the first message in the Transactions section.
    The response and request flows of your API call are shown graphically in the Transaction section (below the Send Requests section). Below the graphic you can see the results of the first step in the request flow.

  8. Click the Next button on the far-right of the window to see how the Spike Arrest policy executed.
  9. Click Next again to see the response from the backend service.
    At each step you can expand the results to get more detail. In this case, expand the Content section so you can see the forecast data that was sent back from the Yahoo weather service. 
  10. In the main menu of the management UI, click APIs to display the API Proxies page.
  11. Click weather in the API Proxies table.
  12. On the weather detail page, click the Develop button to open the API Proxy Editor.
  13. In the Spike Arrest policy, change the value of the <Rate> element to 1ps, and click the Save button to save the current revision with your changes.
  14. Start a new trace session, and make several fast requests to your API, so you make more than one request in a second.

    You will see an HTTP 500 error in the Transactions section of the Trace page when you exceed one request per second. ​If you can't send requests quickly enough to get a 500 response, change the rate to 5pm (5 requests per minute, which Edge enforces at 10 milisecond intervals) and send more requests.

Learn more

Troubleshoot API traffic using Trace

Step 4: Convert XML to JSON

The response from your weather API contains XML data. This can be a problem for developers whose apps want to access the backend service through your API, but only accept JSON responses from their RESTful API calls. You can however add the XML to JSON policy to your API to convert response data from XML to JSON.

With this policy, the payload of an XML message is parsed and converted into JSON, and the content-type is changed to application/json. The policy only works when the source content-type is application/xml. See Convert XML to JSON for details.

To add an XML to JSON policy:

  1. In the management UI, click the APIs tab. If the API Platform page is not open, click here.
  2. Click weather in the API Proxies table.
  3. On the weather detail page, click the Develop button to open the API Proxy Editor.
  4. In the API Proxy Editor, click New policy, and select XML to JSON in the Mediation category.
  5. In the New Policy dialog select the following:
    • Keep the default values for Policy Name and Attach Policy.
    • In the Flow drop-down menu select Flow PostFlow, Proxy Endpoint default.
    • The Response segment radio button.
  6. Click Add.

    The new policy is attached to the PostFlow flow of the response message. Because you selected Flow PostFlow, Proxy Endpoint default, and chose the Response segment, the XML to JSON policy is applied to response messages at the ProxyEndpoint.

    If the XML to JSON policy does not appear in the Designer area of the screen, select PostFlow under Proxy Endpoints in the left navigation area. To see the Spike Arrest policy, select PreFlow under Proxy Endpoints.

  7. Click Save.
  8. Request the URL of the API in a browser, from the Trace page, or from the Apigee Console to see that the response is now formatted as JSON:

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

Learn more

Step 5: Monitor your API's performance

Apigee Edge collects information as data passes through it. The data includes API call information (URL, IP, and user ID) latency, errors, and so on. This data is gathered into trend charts and tables throughout the management UI. You can use this data to both monitor the overall health of your API program and the health of individual APIs. See Use the built-in charts for more information.

Now that you've deployed your API and made requests, you can use the data charts to see metrics.

  1. First, look at the performance of all your APIs. In the management UI, click APIs. If the API Platform page is not open, click here.
  2. If not already selected, select test in the Environment drop-down list at the top of the page. 
  3. Scroll down to the Performance section to the chart displaying metrics for all of your APIs. There may be a few minutes' lag time between when you send requests and when the metrics are available in the charts.
    If you were to make requests over several hours, your chart might look something like this:




    You can show or hide metrics for APIs and policies by clicking their names in the right pane of the chart. You can select different time periods, different types of metrics, and you can move your mouse pointer over the chart to see details about specific data points.

    You probably won't have much data yet. But select a Time Period of one hour to see information about the weather API you just created.
     
  4. Now look at metrics for only your weather API. Click weather in the API Proxies list, click Overview, then scroll down to the Performance section, where you can view metrics for only the weather API and its resources. Again, over several hours of sending requests, your chart might look something like this:



     
  5. For a comprehensive, multi-dimensional view of your entire API program, click Dashboard in the management UI menu. The dashboard provides views of traffic, partner and developer engagement, and top performing APIs, products, apps, and developers. You can view different date ranges and drill down into API traffic details.

    Analytics charts can also be exported to various file formats.


     

Learn more

Use the built-in charts

Next steps: Local development

Although you can use the management UI to perform most of the functions you need to manage your API program, you can also choose to use your own XML editor offline to create and manage APIs in conjunction with the Apigee Edge public API.

Learn more

For more information on local proxy development with the Apigee Edge management API, see API reference getting started.

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