This tutorial walks you through the process of setting up your first API proxyby 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:

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.

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.

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

Leave the "Add Features" section as is.

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.

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

Learn more

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.

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:

In the Resources section of the weather details page, click the + Resource button.

Enter forecast for the Name.

Click the Proxy Endpoint menu and choose default.

Click the Verb menu and choose GET.

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.

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.

Click Save.

To deploy your API proxy, select the Deployment drop-down box in the center of the page.

Learn more

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:

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.

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.