Add and configure your first API

What's here

The Apigee API Platform is an intermediary between apps and services.  You can use it to mediate requests from apps to services that you have developed and deployed yourself, or you can use it to manage APIs exposed by other API providers.

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. Finally, you'll see how to create a developer portal so that third-party developers can find your API.

If you're brand new to the product, you may want to review What is the Apigee API Platform?. If you're new to RESTful APIs you may want to review this blog post for some background. Also take a look at these key concepts. 

 

Step 1: Add an API and define API resources

When you add an API to the Apigee API Platform, you configure an API proxy for one or more existing services. Under the hood, the API Platform 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 the API Platform.

You must first add the Yahoo Weather API:

  1. Login to enterprise.apigee.com. (You can obtain a free account at enterprise.apigee.com/signup.) 
  2. In the API Platform UI, select the APIs tab.

  3. Click the add (+) API button.

  4. Enter WeatherAPI for the Display Name.
  5. Enter Yahoo weather proxy as the description.

  6.  Enter /v1/weather as the API Proxy URL.

    API Proxy URL defines the proxy URL that apps call to invoke your API. The  API Platform 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 orgnization. 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: http://apifactory-test.apigee.net/v1/weather.
     
  7. Enter http://weather.yahooapis.com as the Backend Service URL.

    Backend Service URL defines the target URL that the API Platform invokes on behalf of apps. You can add any URL that is accessible over the open Internet. 

    Now you're ready to define your first resource. Defining API resources is completely optional. In steps 5 and 6 you configured everything you need to manage the Yahoo Weather API.  

    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.  
     
  8. In the Resources section, click the Verb menu and choose GET.
  9. Enter /forecastrss as the Resource Path. By defining this URI, you can monitor and manage it specifically. 
  10. Enter Forecast for the Display Name.
  11. Enter Weather forecasts in the Description field.
  12. Click Done in the bottom right corner of the page.

The API platform 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.

Call Yahoo Weather API via the API

Now that you have a proxy for the Yahoo Weather API you can invoke it indirectly, via the API Platform. 

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

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

Learn more

Add APIs

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.

The API proxy editor lets you see the structure of your API proxy and configure its flow. The editor is a visual representation of your proxy's message flows as well as an editable display of the XML that defines the proxy.

Set a rate limit for your API

To help you learn how to configure APIs, you're going to add a couple of policies to the WeatherAPI you created. First, you'll adjust the default Spike Arrest policy to protect your backend from high traffic.

  1. In the main menu, click APIs to display the APIs page.
  2. Click WeatherAPI.
  3. On the WeatherAPI detail page, click the Edit API Proxy button.

  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.

    Spike arrests are a way to stop traffic spikes (or bursts) that can be caused by an increase in usage, buggy clients, or malicious attacks. In response, you’ll see the New Policy dialog which displays:

    • 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 (of the assigned name) is attached to the request message flow. This means that the API Platform 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 will be applied to request messages at the ProxyEndpoint.

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

  7. Examine what’s been added to the API proxy editor:
    • The Spike Arrest policy is added to various views in the proxy editor.
    • The policy is added to the list of policies in the Navigator view.
    • The policy is added to the Designer view, which is a visual representation of your proxy's message flows.
    • The XML for the policy is displayed in the Code view.
    • The XML element and attribute values for the policy are displayed in the Property Inspector.

  8. In the XML for the policy, change the value of the <Rate> element to 75ps.

    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.

  9. Click the Project button, then select Save in the drop-down menu to save the current revision with your changes.

Convert XML to JSON

Suppose your API provides responses in XML. 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 provide a policy that converts data sent by the service from XML to JSON.

In this type of policy, the payload of an XML message is parsed and converted into JSON. 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 API proxy editor, click New policy, and select XML to JSON in the Mediation category.
  2. In the New Policy dialog select the following:
    • Flow PostFlow, Proxy Endpoint default, in the Flow drop-down menu.
    • The Response segment radio button.
    • Keep the default values for Policy Name and Attach Policy.
  3. Click Add.

    The new policy is attached to the response message flow. 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.

  4. Click the Project button, then select Save in the drop-down menu.
  5. Click Deployment, then Test.

    The updated API proxy replaces the revision currently deployed in your test environment.

    Note: Depending on your role, you may not be able to deploy to all environments. Users can deploy only to the test environment. Administrators can deploy to any environment.

Learn more

Step 3: 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 WeatherAPI is not live you'll send calls manually so you can see how policies are being executed.

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

  2. Click the WeatherAPI in the summary table.
  3. On the WeatherAPI detail page, click Trace > test. This will let you set up a Trace session on the test environment.

  4. Click Listen.
    While the Trace session is Listening, messages are captured from live traffic.

    Since your API has not be exposed to developers, you won't have any traffic. In this case, you can use the Apigee Console to send a message directly to your API. 
     
  5. Click Open the Apigee Console.
    The console appears in another window displaying your facade URL.
  6. Click Send.
    This sends a call to your API. You can click send multiple times to generate as much traffic as you wish.
  7. Switch back to Apigee and click Stop.
    The call appears in the Captured Messages section.
  8. Click the first message.
    The response and request flows of your API call are shown graphically at the top of the window. Below the graphic you can see the results of the first step in the request flow.
  9. Click the Next button on the far-right of the window to see how the Spike Arrest policy executed.
  10. 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. 

Learn more

Troubleshoot API traffic using Trace

Step 4: Add an API Product

An API product is a collection of API resources combined with a service plan and presented to developers as a bundle. The product can also include some metadata specific to your business for monitoring or analytics.

API Products are the central mechanism for authorization and access control to your APIs. In the API Platform, API Keys are provisioned, not for APIs themselves, but instead for API products. In other words, API Keys are provisioned for bundles of URIs with an attached service plan. See Set up API products for more information.

Do this

  1. In the API Platform UI, click the Products tab. If the API Platform is not open, click here.

  2. Click the + Product button.
  3. Enter Tutorial Product for the Name and My tutorial API product for the description.
  4. Select test as the environment, and then select Internal only for the access level.
    This limits access to the developers in your organization.
  5. Enter 500 as the Service Limits and select Week.
  6. Enter Read as the Scope.
  7. In the API Details section, click the API & Resource paths menu and choose weatherAPI. Leave the other menu as is. This indicates that you'll be adding all the API's resources to the product.

  8. Click Add API, and then click Done.
    You'll see your new product in the Products list.

Learn more

What is an API product?

Step 5: Activate an API product

Before you can use your API product you need to make sure it supports the client credentials form of OAuth 2.0 (aka “two-legged OAuth”), so it requires a valid OAuth token on every API call. To do this you'll need to attach a policy to set up key validation.

Add policy for key validation

An API Key Validation policy verifies the API key for an API product defined in the API Platform, returns an error if it is invalid, and if it is valid, looks up the attributes from the API product.

To add an API Key Validation policy:

  1. In the API proxy editor, click New Policy, and select Validate API Key in the Security category.
  2. Accept the defaults in the New Policy dialog and click Add.
  3. Click the Project  button, then select Save in the drop-down menu to save the the current revision.

The new policy is attached to the request message flow at the ProxyEndpoint.

Deploy the API

Finally, you can deploy the revision you've been working on.

Do this

On the top of the screen, click the Deployment button and select test. This will replace the existing API with your new secure API. 

Learn more

Enforce access control using VerifyAPIKey

Step 6: Add a developer and app

Add a developer

Now that you have an API product, you need to add a developer to your organization. Developers can be individuals or groups. For example an API team. For this tutorial, you'll add a developer to the system. Developers can also add themselves by registering with your organization through your developer portal. See Set up your developer portal for information on setting up a portal.

To add a developer:

  1. In the API Platform, click the Developers tab. If it's not open, click here.

  2. Click the + Developer button.
  3. In the prompt, enter Jane Tutorial for the developer first and last name, and janetutorial@sample.com for the email address.
  4. Click Save.
    The new developer appears in the Developer list.

Add an App

Create an application so that you can generate a key for your API products. The key can be distributed to your developers so they can access the features in the API products you've created. Your developers can also create their own apps using your developer portal.

To add an app:

  1. In the API Platform, click the Apps tab.

  2. Click the + App button.
  3. Enter Tutorial Weather App for the Name.
  4. Enter www.example.com as your callback URL.
  5. Select Jane Tutorial as your developer.
  6. Click Save.
    The new app appears in the Apps list.

Associate the App with an API Product

Associate the application with the API Product you created.

To associate the app with an API Product:

  1. In the API Platform, click the Apps tab.
  2. Select Tutorial Weather App in the Apps list.
  3. Select Tutorial Product from the API Product drop-down menu.

  4. Click Add. The API product is added to the Products Used list for the App.

Generate the key

Finally, generate the key for the API Product.

Do this:

In the Products Used list, Click Approve in the Actions column for the Tutorial Product. The key will appear in the Key column.

Test your API Product

Now that you have a developer, app, product, and key, you can test to see if calls are being handled properly. You'll need to include the key in a call you make to the API.

Do this:

  1. In the API Platform, click the Apps tab.
  2. Click on Tutorial Weather App in the Apps summary table. 
  3. Click the link under the Keys column. In the pop-up that appears, copy the Consumer Key.
  4. Open your favorite API console (or the Apigee Console) and make a call to your API such as:

    http://apigee-<your org>-test.apigee.net/v1/weather/forecastrss?w=12797282
     
  5. Add this to the end of your call:&apikey= so your call now looks something like this:

    http://apigee-<your org>-test.apigee.net/v1/weather/forecastrss?w=12797282&apikey=
     
  6. Paste the key you copied earlier onto the end of the call so that your final call looks something like this:

    http://apigee-<your org>-test.apigee.net/v1/weather/forecastrss?w=12797282&apikey=kFE4NmKv8edjdEieipzFt6d5YGZqeP50
     
  7. Hit Send.

    If everything is working properly you should get a response that includes weather information for Palo Alto, CA.

Learn more

Give developers access to your API

Step 7: Set up a developer portal

You're now ready to share your APIs with your developer community. Apigee's API Platform lets you set up a developer portal that you can use to publish your APIs, documentation, and terms of use. Your developers can use your portal to register with your organization and set up their apps to get keys.

The portal also has built-in blogs and forums to help grow your community, and a test console you can use to trace your API calls in real time. The developer portal template is based on the open source Drupal (www.drupal.org) project. You can also set up permissions to control manual/automatic user registration and to moderate user comments.

Do this

  1. In the API Platform, click the Developers tab. If it's not open, click here.

  2. Click the Dev Portal icon.

    Add developer portal

  3. Respond to the prompt:

    What is your developer portal's target Select Public developer
    What is the main goal of your developer portal? Select Developer onboarding
    What is you preferred content management system (e.g., Drupal, WordPress)? Enter Drupal

     

  4. Click Save. The API Platform will provision a new developer portal for your org. You'll recieve an email with a link to your new portal. Once you access your portal you can customize it. See Set up your developer portal for more information.

Learn more

What is a developer portal?

Step 8: Monitor your API's performance

Apigee's API gateway 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 API Platform UI. You can use this data to both monitor the health of your API program overall and the health of individual APIs. See Monitor the performance of your API for more information.

Now that you've deployed your API, you can use the data charts to see how it's being used.

  1. Click the Apigee logo in the main menu.
    This takes you to the main dashboard.
  2. Verify that Sample data is turned off (that is the Show Simulated Data checkbox is unchecked).

  3. Click the All APIs button.
    This takes you to the APIs summary table, which displays statistics for all the APIs in your organization. You can use this data to get a sense of the operational efficiency of your systems. You can quickly see anomalies in traffic data that can indicate an issue with your backend systems.
  4. Find weatherapi in the table. For this API, you can see:

    Message Count The number of calls this API has recieved.
    Message Trend by hour A visual representation of the traffic for this API. You can quickly see where there were spikes in traffic.
    Average Response Time The time an API takes to respond to an incoming request.
    Error rate The fraction of all API requests that are unsuccessful (the request does not deliver a response as desired by the end user).
    Average Data Exchange The size of request and response. That is, the amount of data that is transferred in both directions as a request for an API is serviced and a response is generated and delivered to the calling entity.
  5. Navigate to the Performance section at the bottom of the table.
    These controls let you adjust the metrics for the chart that appears at the bottom of  the page. The chart shows a visual representation of the throughput for each of your APIs.

  6. Click the Showing Data for the Last menu and change the time period to 1hr. The API table and performance chart change to show traffic over the last hour.
  7. Click the Metric menu and choose Maximum Response Time.
    The table updates to show you the maximum response time over the last hour.

Learn more

Monitor the performance of your API

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 to create and manage APIs using the API Platform's public API.

Learn more

You do not have access to view this node