Building a simple API proxy

This page applies to Apigee and Apigee hybrid.

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:

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:

  1. Sign in to the Apigee UI.
  2. In the navigation bar, select Develop > API Proxies.
  3. Click Create New.
    Create proxy button

The Create Proxy wizard displays and leads you through the steps to generate and add minimal features to an API proxy.

First page of the Create Proxy wizard prompting you to select reverse proxy, No Target, or Proxy bundle to customize the wizard flow.

The first page of the wizard enables you to create an API proxy from the following sources:

Type Description
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 information on this option, see Using OpenAPI Specifications to generate proxies later in this section.
No target

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 information 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).

The following Proxy details are available after accessing the Create Proxy wizard and selecting a proxy type:

Field Description
Name Name displayed for your API. Specify alphanumeric characters, dash (-), or underscore (_).
Base path

URI fragment that appears after the http://[host] or https://[host] address of your API proxy. Apigee uses the base path URI to match and route incoming request messages to the proper API proxy.

Following the base path are any additional resource URLs. The full URL structure that clients use to call your API proxy is as follows:

https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH

Use wildcards in base paths

Use one or more /*/ wildcards in API proxy base paths to future-proof your API proxies. For example, a base path of /team/*/members allows clients to call https://[host]/team/blue/members and https://[host]/team/green/members without you needing to create new API proxies to support new teams. Note that /**/ is not supported.
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:

  1. Access the Create Proxy wizard as described in Creating an API proxy using the UI previously in this section.
  2. Click Upload proxy bundle.

  3. 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.
  4. Click Next.

  5. 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.

  6. Click Edit proxy to display the details page for the API proxy.

Creating gRPC API proxies

In addition to REST API proxies, Apigee supports gRPC API proxies with passthrough support only at this time. With passthrough support, the gRPC payload is itself opaque to Apigee and the traffic is routed from the gRPC client to the preconfigured gRPC target server in the target configuration.

At this time, Apigee gRPC API proxies:

  • Support unary gRPC requests.
  • Can't use policies that affect the payload.
  • Can be used in API products that are not associated with GraphQL or REST proxies. API product-specific quotas and other operation settings apply across all proxies in the product.
  • Are not supported in Apigee hybrid.
  • Use two gRPC-specific flow variables: request.grpc.rpc.name and request.grpc.service.name.
  • Can be monitored with these gRPC-specific Apigee Analytics variables: x_apigee_grpc_rpc_name, x_apigee_grpc_service_name, and x_apigee_grpc_status.
  • Return gRPC status codes.

You must also configure your load balancer to support gRPC. See Using gRPC with your applications and Using gcloud CLI commands to create routing for gRPC.

To create a gRPC API proxy, first define a gRPC target server (see Creating TargetServers) and then specify that target server when creating the new proxy.

Using gcloud CLI commands to create routing for gRPC

This section shows example commands for creating routing for gRPC proxies, using the gcloud CLI. The instructions include setting up load balancers, a target server, and a MIG.

This section is not as a comprehensive guide to creating the routing. These examples might not be appropriate for all use cases. Also, these instructions assume familiarity with External routing (MIG) and Cloud load balancer gRPC configuration.

Set environment variables

These environment variables are used in the commands in the subsections. 

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Adding security

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:

Security authorization Description
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.

Adding Quotas

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?

Open API Initiative logo   "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.

The following fragment from an OpenAPI Specification describes Apigee's mock target service, http://mocktarget.apigee.net. For more information, see OpenAPI spec for the helloworld sample.

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:

  1. Sign in to the Apigee UI.
  2. In the navigation bar, select Develop > API Proxies.
  3. Click the API proxy in the list that you want to copy.

  4. Click the Develop tab.

  5. Select the Save button and select 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.