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 Edge uses to create the API proxy that is exposed to developers.
The API proxy 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.
Watch this video for an overview of the process of creating an API proxy.
The easiest way to create an API proxy is using the Edge management UI:
- Log in into the Edge management UI.
- From the main menu, select APIs > API Proxies
A list of all API proxies in your organization displays.
- To create a new API proxy, select add (+) API Proxy button.
The New API Proxy form is displayed.
Use this form to provide the information needed to generate an API proxy and, optionally, to add some minimal features to the API proxy:
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 creating API proxies with Node.js, see Developing Node.js applications for Apigee Edge.
Edge 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:
- 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.
- Under Identify Your API Proxy:
- Enter a descriptive name for your API, such as
- 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.
- Enter a descriptive name for your API, such as
- Optionally, add security and CORS support to your API.
See Adding security and CORS support to your API for more information.
- 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.
- The new API is immediately available to be invoked.
- See Part 1: Create your API for a complete tutorial on creating an API proxy in the Edge management UI.
Often you define API proxies as a collection of XML files, along with any other supporting files. By defining your API proxies as a set of files external to Edge you can maintain them in a source-control system, and then import them into Edge for testing and deployment.
Apigee provides a set of API proxy samples as bundles on GitHub that you can download, examine, modify, and upload to Edge. See Using the sample API proxies for more.
To import API proxies from a set of files:
- Under Choose Your Starting Point section of the New API Proxy form:
Apigee API Bundle
- Click Choose File
- Navigate to the ZIP file containing the API proxy configuration
- Under Identify Your API Proxy, enter a descriptive name for your API.
- 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.
- See Part 1: Create your API in XML for a complete tutorial on creating an API proxy from an API bundle.
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.
When you add an API proxy for an existing backend service, 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.
If you import an API bundle, then you are responsible for configuring security in the bundle. The UI does not prompt you to add security when importing the bundle.
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?
- See Part 1: Create a secure API for a complete tutorial on applying security to and API proxy in the Edge management UI.
- See Part 1: Create a secure API in XML for a complete tutorial on applying security to an API proxy from an API bundle.
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.