—Rate this article—
 

Build a simple API proxy

Apigee Edge enables you to quickly expose backend services as APIs. You do this by creating an API proxy that provides a facade for the backend service that you want to expose. You only need to provide the network address for the backend service, along with some information that API Services uses to model the API that will be exposed to developers. 

The API proxy that you create on Edge decouples your backend service implementation from the API that developers consume. This shields developers from future changes to your backend services. As you update backend services, developers, insulated from those changes, can continue to call the API uninterrupted.

This topic shows you how to create a simple API proxy that runs on Edge.

Watch this video for an overview of the process.

Creating an API proxy

The easiest way to create an API proxy is using the API proxy builder tool, which is available in the Edge management UI. 

  1. Log in into the Edge management UI.
  2. From the main menu, select APIs > API Proxies

A list of all API proxies in your organization displays.

  1. To create a new API proxy, select add (+) API Proxy button.

    The New API Proxy form is displayed.

Use this form to provide API Services with the information it needs to generate an API proxy and, optionally, to add some minimal features to the API that is exposed.

This form enables you create an API proxy from the following sources:

  • An existing HTTP service (this could be a JSON or XML API)
  • An existing API proxy bundle (for example one of the sample API proxies available on GitHub.)
  • A WSDL file
  • An API proxy with no API backend ("No target")
  • A Node.js application

The following sections describe how to create an API proxy using each source.

For Node.js, see Developing Node.js applications for Apigee Edge.

Generating an API proxy for an HTTP service

API Services generates API proxies based on two pieces of information:

  • The URL of the backend service
  • The URI path that uniquely identifies the API that will be exposed by the API proxy to consumer apps

The backend service URL typically represents a service-enabled application owned by your organization. It can also point to a publicly available API. The API or service can be under your control (for example, an internal HR application or a Rails application in the Cloud) or it can be a third-party API or service (for example, Twitter or Instagram). 

To add an API proxy for an existing HTTP service:

  1. Under Choose Your Starting Point:
    • Select Existing Backend service.
    • Enter the Backend Service URL, for example, http://weather.yahooapis.com. The Backend Service URL defines the target URL that Edge invokes on behalf of apps. You can add any URL that is accessible over the open Internet.
  2. Under Identify Your API Proxy:
    • Enter a descriptive name for your API, such as weather.
    • Enter a Project Base Path.

      The Project Base Path is a URI fragment that uniquely identifies the API that is exposed by this API proxy. API Services uses the Base Path URI to match and route incoming request messages to the proper API proxy. (The Base Path is appended to the domain of the API, which is automatically generated based on your organization name and the environment where the API proxy is deployed.) It's a best practice to include a version number in the project name, for example, /v1/weather. This will determine how your API is invoked by consumer apps.

    • Optionally, add a brief description of the API.
  3. Optionally, add security and CORS support to your API.
    See Adding security and CORS support to your API for more information.
  4. Select Build
    In response, you should see an acknowledgment that your new API proxy was successfully generated. API Services automatically deploys the newly generated API proxy to the 'test' environment in your organization.
  5. The new API is immediately available to be invoked.

Importing API proxies

You can use this capability to import sample API proxies, or to import any API proxies that you or other developers have configured. 

  1. Under Choose Your Starting Point section of the New API Proxy form:
    • Select Apigee API Bundle
    • Click Choose File
    • Navigate to the ZIP file containing the API proxy configuration
  2. Under Identify Your API Proxy, enter a descriptive name for your API.
  3. Select Build
    In response, you should see an acknowledgment that your new API proxy was successfully imported. API Services automatically deploys the imported API proxy to the 'test' environment in your organization. The API exposed by the API proxy is available to be invoked.

Exposing a SOAP-based web service as an API proxy

You can create two kinds of SOAP proxies in Edge. One generates a RESTful interface to the backend SOAP service and the other performs a "pass through" of the SOAP message to the backend. For details, see Exposing a SOAP service as an API proxy.

Adding security and CORS support to your API

When you add an API proxy for an existing backend service or import an existing API bundle, the New API Proxy page displays an Add Features section in which you can add features to your API such as security and support for CORS.

Adding security

Check Security with API Keys to add simple API key verification to the API proxy that you are defining. In response, the API Platform adds a VerifyAPIKey policy and an AssignMessage policy to your API proxy. The VerifyAPIKey policy validates API keys presented by requesting apps. The AssignMessage policy strips the API key, supplied in the API call as a query parameter, from the request forwarded to the backend server.

If you select Secure with OAuth v2.0 Access Tokens, Edge will automatically add two policies to your API proxy: one policy to verify an access token and another policy to strip the access token from the message before forwarding it to your backend service. To learn how to obtain an access token, see OAuth.

When you check Secure with API Keys, the New API Proxy page updates as follows:

  • The Impose Quota per Developer checkbox becomes selectable. Check this to add a Quota policy to your API proxy that enforces a limit on the traffic to your API from individual apps.
  • The Publish API Product checkbox becomes selectable and is automatically selected. Check this if you want to automatically generate a product when you build the new API proxy. The autogenerated product will be created with an association to the new API proxy. If you have an existing product with which you want to associate this new API, be sure to clear this checkbox so that you don't create an unnecessary product. For information about products, see What is an API product?

Adding support for CORS

CORS (Cross-origin resource sharing) is a standard mechanism that allows a Web browser to make direct requests to another domain. The CORS standard defines a set of HTTP headers that Web browsers and servers use to implement cross-domain communication.

You can add support for CORS to your API by selecting the Enable Direct Browser Access for your API checkbox under Add Features. For more detailed information about CORS support, including adding CORS preflight support to a proxy, see Adding CORS support to an API proxy.

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