viewing Apigee X documentation.
View Apigee Edge documentation.
Apigee 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 need to provide only the network address for the backend service, along with some information that Apigee 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.
This topic provides information about the various types of proxies and the settings for them. For step-by-step instructions on creating proxies, see the following topics:
Watch the following video for an overview of the process of creating an API proxy:
Creating an API proxy using the UI
The easiest way to create an API proxy is using the Create Proxy wizard.
To access the Create Proxy wizard using the Apigee UI, perform the following steps:
- Sign in to the Apigee UI.
- In the navigation bar, select Develop > API Proxies.
- Click Create New.
The Create Proxy wizard displays and leads you through the steps to generate and add minimal features to an API proxy.
The first page of the wizard enables you create an API proxy from the following sources:
|Reverse proxy (most common)||
An API proxy that routes inbound requests to existing HTTP backend services. Can be a JSON or XML API. See Creating a reverse proxy for an HTTP service later in this section.
Click Use OpenAPI Spec to generate the proxy from a valid OpenAPI Specification. For more informations on this option, see Using OpenAPI Specifications to generate proxies later in this section.
An API proxy with no API backend ("no target"). Similar to Creating a reverse proxy for an HTTP service described previously, except you will not specify an existing API when defining the API proxy details.
Click Use OpenAPI Spec to generate the proxy from a valid OpenAPI specification. For more informations on this option, see Using OpenAPI Specifications to generate proxies later in this section.
|Upload proxy bundle||An existing API proxy bundle (for example one of the sample API proxies available on GitHub). See Importing an API proxy from an API proxy bundle.|
The following sections discuss the details of each proxy type.
Creating a reverse proxy for an HTTP service
Apigee generates reverse proxies based on the following information:
- URL of the backend service.
- 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).
|Name||Name displayed for your API. Specify alphanumeric characters, dash (-), or underscore (_).|
URI fragment that appears after the
Following the base path are any additional resource URLs. The full URL structure that clients use to call your API proxy is as follows:
Use wildcards in base paths
Use one or more
|Description||(Optional) Description of the API.|
|Target (Existing API)||URL of the backend service that this API proxy invokes.|
Importing an API proxy from an API proxy bundle
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 Apigee you can maintain them in a source-control system, and then import them into Apigee for testing and deployment.
To import API proxies from an API proxy bundle, perform the following steps:
- Access the Create Proxy wizard as described in Creating an API proxy using the UI previously in this section.
- Click Upload proxy bundle.
On the Upload proxy bundle page in the proxy wizard, enter the following information:
Field Description ZIP bundle ZIP file containing the API proxy configuration. Drag and drop or click to navigate to the file. Name Name displayed for your API. Defaults to the name of the ZIP file without the extension.
- Click Next.
On the Summary page, select the deployment environments, if desired, and click Create and deploy
An acknowledgment is displayed confirming that your new API proxy was successfully created.
- Click Edit proxy to display the details page for the API proxy.
On the Common policies page of the Create Proxy wizard, select the type of security authorization you wish to add. The following table summarizes the available options:
|API Key||Adds 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.|
|OAuth 2.0||Adds OAuth 2.0 based authentication to your API proxy. Apigee automatically adds the following 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.|
|Pass through (no authorization)||No authorization required. Requests are passed to the backend without any security checks on Apigee.|
Adding support for CORS
Cross-origin resource sharing (CORS) 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 by doing one of the following:
- Adding the CORS policy to the request PreFlow of the ProxyEndpoint
- Selecting Add CORS headers on the Common policies page of the Create Proxy wizard
For more detailed information about CORS support, including adding CORS preflight support to a proxy, see Adding CORS support to an API proxy.
Quotas protect your backend service from high traffic under Quota. See Quotas. (Not available if Pass-through authorization is selected.)
Using OpenAPI Specifications to generate proxies
This section discusses the Use OpenAPI option that is available for generating from an OpenAPI Specification the following types of API proxies: reverse or no target.
What is an OpenAPI Specification?
"The Open API Initiative (OAI) is focused on creating, evolving and promoting a vendor neutral API description format based on the Swagger Specification." For more information, see OpenAPI Initiative.
An OpenAPI Specification uses a standard format to describe a RESTful API. Written in either JSON or YAML format, an OpenAPI Specification is machine readable, but is also easy for humans to read and understand. The specification describes API elements such as its base path, paths and verbs, headers, query parameters, operations, content types, response descriptions, and more. In addition, an OpenAPI Specification is commonly used to generate API documentation.
openapi: 3.0.0 info: description: OpenAPI Specification for the Apigee mock target service endpoint. version: 1.0.0 title: Mock Target API paths: /: get: summary: View personalized greeting operationId: View a personalized greeting description: View a personalized greeting for the specified or guest user. parameters: - name: user in: query description: Your user name. required: false schema: type: string responses: "200": description: Success /help: get: summary: Get help operationId: Get help description: View help information about available resources in HTML format. responses: "200": description: Success ...
Through the Create Proxy wizard, you can import an OpenAPI Specification and use it to generate an API proxy. Once the proxy is generated, you can use the Apigee UI to further develop it by adding policies, implementing custom code, and so on&emdash;just like any Apigee proxy.
Creating an API proxy from an OpenAPI Specification
Create your API proxies from an OpenAPI Specification. In just a few clicks, you'll have an API proxy with the paths, parameters, conditional flows, and target endpoints generated automatically. Then, you can add features such as OAuth security, rate limiting, and caching.
In the Create Proxy wizard, click Use OpenAPI Spec and follow the wizard to create a reverse or no target proxy from an OpenAPI Specification. For details, see Creating an API proxy from an OpenAPI Specification.
Creating a new revision of an API proxy
Create a new revision of an API proxy, as described below.
To create a new revision of an API proxy, perform the following steps:
- Sign in to the Apigee UI.
- In the navigation bar, select Develop > API Proxies.
- Click the API proxy in the list that you want to copy.
Click the Develop tab.
- Select Save > Save as New Revision.
Backing up an API proxy
You can back up an existing API proxy as a set of XML files in an API proxy bundle. Once exported to a bundle, you can import the API proxy to a new proxy, as described in Importing an API proxy from an API proxy bundle previously in this section. For more information, see Download API proxies.
Creating an API proxy using the API
To create an API proxy using the API, see Creating an API proxy.