Building a simple API proxy

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

Note: In environments enabled forarchive deployments, you cannot build API proxies using the Apigee UI, API, or gcloud.To build API proxies for archive deployments using Apigee in VS Code,seeDeveloping API proxies using Apigee in VS Code.

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 theCreate Proxy wizard.

Apigee UI in Cloud Console

  1. In the Google Cloud console, go to theProxy development> API proxies page.

    Go to API proxies

  2. Click+ Create.

Classic UI

To access theCreate Proxy wizard using the Apigee UI, perform the following steps:

  1. Sign in to theApigee UI.
  2. In the navigation bar, selectDevelop > API Proxies.
  3. ClickCreate New.
    Create proxy button

TheCreate 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 to create an API proxy from the following sources:

TypeDescription
Reverse proxy (most common)

An API proxy that routes inbound requests to existing HTTP backend services. Can be a JSON or XML API. SeeCreating a reverse proxy for an HTTP service later in this section.

ClickUse OpenAPI Spec to generate the proxy from a valid OpenAPI Specification. For more information on this option, seeUsing OpenAPI Specifications to generate proxies later in this section.

No target

An API proxy with no API backend ("no target"). Similar toCreating a reverse proxy for an HTTP service described previously, except you will not specify an existing API when defining the API proxy details.

ClickUse OpenAPI Spec to generate the proxy from a valid OpenAPI specification. For more information on this option, seeUsing OpenAPI Specifications to generate proxies later in this section.

Upload proxy bundleAn existing API proxy bundle (for example one of thesample API proxies available on GitHub). See Importing an API proxy from an API proxy bundle.
Proxy with Server-Sent Events (SSE)An API proxy that includes anEventFlow for streaming server-sent events (SSE). For more information, seeStreaming server-sent events.

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 followingProxy details are available after accessing theCreate Proxy wizard and selecting aproxy type:

FieldDescription
NameName displayed for your API. Specify alphanumeric characters, dash (-), or underscore (_).
Base path

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

Note: The API proxy base path defaults to the value specified for theName field converted to all lower case.

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

Note: The base path must be unique; you cannot deploy two API proxies with the same base path. If you edit a deployed API proxy and set the base path to the same value as the base path of another API proxy, Apigee automatically undeploys the API proxy when you save it. Before you can redeploy the API proxy, you must edit the base path so that it is unique.

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 callhttps://[host]/team/blue/members andhttps://[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

Note: When importing an API proxy from an API proxy bundle, you are responsible for configuring security in and adding policies to the bundle. The UI does not prompt you to add security or policies when importing the bundle, as described inAdding security later in this section.

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 theCreate Proxy wizard as described inCreating an API proxy using the UI.
  2. Specify the API proxy bundle details.

    3. Apigee UI in Cloud Console

    1. In theProxy template menu, selectUpload proxy bundle.
    2. In theProxy details section, enter theProxy name, upload the zip file and clickNext.
    3. In theDeploy section, select the deployment environments, if desired, and clickCreate.

    Classic UI

    1. ClickUpload proxy bundle.

    2. On theUpload proxy bundle page in the proxy wizard, enter the following information:

      FieldDescription
      ZIP bundleZIP file containing the API proxy configuration. Drag and drop or click to navigate to the file.
      NameName displayed for your API. Defaults to the name of the ZIP file without the extension.
    3. ClickNext.

    4. On theSummary page, select the deployment environments, if desired, and clickCreate and deploy.

      An acknowledgment is displayed confirming that your new API proxy was successfully created.

    5. ClickEdit proxy to display the details page for the API proxy.

Creating gRPC API proxies

In addition to REST API proxies, Apigee supports gRPC API proxieswith passthrough support only at this time. Withpassthrough 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-specificflow variables:request.grpc.rpc.name andrequest.grpc.service.name.
  • Can be monitored with these gRPC-specificApigee Analytics variables:x_apigee_grpc_rpc_name,x_apigee_grpc_service_name, andx_apigee_grpc_status.
  • ReturngRPC status codes.

You must also configure your load balancer to support gRPC. SeeUsing gRPC with your applications andUsing gcloud CLI commands to create routing for gRPC.

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

Note: gRPC proxy configuration through the Apigee UI is supported through theApigee UI in Cloud Console only, not other Apigee consoles.

Using gcloud CLI commands to create routing for gRPC

This section shows example commands for creating routing for gRPC proxies, using thegcloud 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 withExternal routing (MIG) andCloud load balancer gRPC configuration.

Set environment variables

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

PROJECT_ID=YOUR_PROJECT_IDMIG_NAME=YOUR_MIG_NAMEVPC_NAME=defaultVPC_SUBNET=defaultREGION=REGION_NAMEAPIGEE_ENDPOINT=ENDPOINTCERTIFICATE_NAME=CERTIFICATE_NAMEDOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Example gcloud CLI commands for creating routing for gRPC proxies using new load balancers

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

Create the instance template

gcloudcomputeinstance-templatescreate$MIG_NAME\--project$PROJECT_ID\--region$REGION\--network$VPC_NAME\--subnet$VPC_SUBNET\--tags=https-server,apigee-mig-proxy,gke-apigee-proxy\--machine-typee2-medium--image-familydebian-12\--image-projectdebian-cloud--boot-disk-size20GB\--no-address\--metadataENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

Create the managed instance group

gcloudcomputeinstance-groupsmanagedcreate$MIG_NAME\--project$PROJECT_ID--base-instance-nameapigee-mig\--size2--template$MIG_NAME--region$REGION

Configure autoscaling

gcloudcomputeinstance-groupsmanagedset-autoscaling$MIG_NAME\--project$PROJECT_ID--region$REGION--max-num-replicas50\--target-cpu-utilization0.75--cool-down-period90

Define a named port

gcloudcomputeinstance-groupsmanagedset-named-ports$MIG_NAME\--project$PROJECT_ID--region$REGION--named-portshttps:443

Create a Google-managed SSL certificate and key for the load balancer

gcloud compute ssl-certificates create $CERTIFICATE_NAME \--domains=$DOMAIN_HOSTNAME \--project $PROJECT_ID \--global

Validate that the certificate is provisioned

gcloud compute ssl-certificates describe $CERTIFICATE_NAME \--global \--format="get(name,managed.status, managed.Status)"

Create the Global Cloud Load Balancer (GCLB)

  1. Create a health check
    gcloud compute health-checks create https hc-apigee-envoy-443 \--project $PROJECT_ID --port 443 --global \--request-path /healthz/ingress
  2. Create the backend service for http1
    gcloudcomputebackend-servicescreateYOUR_BACKEND_1\--project$PROJECT_ID\--protocolHTTPS\--health-checkshc-apigee-envoy-443\--port-namehttps\--timeout302s\--connection-draining-timeout300s\--global
  3. Create the backend service for http2
    gcloudcomputebackend-servicescreateYOUR_BACKEND_2\--project$PROJECT_ID\--protocolHTTP2\--health-checkshc-apigee-envoy-443\--port-namehttps\--timeout302s\--connection-draining-timeout300s\--global
  4. Add MIGs to the backend service. In this example we are reusing the MIG, but you could also create a new pair of MIGs.
    gcloudcomputebackend-servicesadd-backendYOUR_BACKEND_1\--project$PROJECT_ID--instance-group$MIG_NAME\--instance-group-region$REGION\--balancing-modeUTILIZATION--max-utilization0.8--global
    gcloudcomputebackend-servicesadd-backendYOUR_BACKEND_2\--project$PROJECT_ID--instance-group$MIG_NAME\--instance-group-region$REGION\--balancing-modeUTILIZATION--max-utilization0.8--global
  5. Create a load balancing URL map. Check first whether you already have a URL map. If you do, make sure to modify that map according to the requirements below rather than overwrite it.

    Create a YAML file or use your existing file, at/tmp/apigee-map.yaml, with this configuration. Note that the URL map http1 backend is default.

    defaultService:projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_1name:matcher1routeRules:-matchRules:-headerMatches:-headerName:Content-TypeprefixMatch:application/grpcprefixMatch:/priority:100routeAction:weightedBackendServices:-backendService:projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_2weight:100

    Validate the URL map:

    gcloud compute url-maps validate --source /tmp/apigee-map.yaml --project $PROJECT_ID

    Create the url map with header-based routing:

    gcloudcomputeurl-mapsimportapigee-http1-http2 \--source/tmp/apigee-map.yaml  \--global--project$PROJECT_ID

Create a load balancing target HTTPS proxy

gcloud compute target-https-proxies create apigee-envoy-https-proxy \--project $PROJECT_ID --url-map apigee-envoy-proxy-map \--ssl-certificates $CERTIFICATE_NAME

Reserve an IPV4 External IP and create firewall rules for the load balancer

gcloudcomputeaddressescreatelb-ipv4-vip-1\--project$PROJECT_ID\--network-tier=PREMIUM\--ip-version=IPV4\--globalgcloudcomputeaddressesdescribelb-ipv4-vip-1\--project$PROJECT_ID--format="get(address)"--globalgcloudcomputeforwarding-rulescreateapigee-envoy-https-lb-rule\--project$PROJECT_ID--addresslb-ipv4-vip-1--global\--target-https-proxyapigee-envoy-https-proxy--ports443

Create a firewall rule

gcloud compute firewall-rules create k8s-allow-lb-to-apigee-envoy \--description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \--project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \--source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

Example gcloud CLI commands for creating routing for gRPC proxies for existing load balancers

This section shows example commands for creating gRPC proxies using thegcloud CLI and an existing load balancer. The instructions include setting up the load balancer, a target server, and a MIG.

Create another backend service for http2

#Createbackendserviceforhttp2gcloudcomputebackend-servicescreateYOUR_BACKEND_2\--project$PROJECT_ID\--protocolHTTP2\--health-checkshc-apigee-envoy-443\--port-namehttps\--timeout302s\--connection-draining-timeout300s\--global

Attach the second backend service to the MIG

gcloudcomputebackend-servicesadd-backendYOUR_BACKEND_2\--project$PROJECT_ID--instance-group$MIG_NAME\--instance-group-region$REGION\--balancing-modeUTILIZATION--max-utilization0.8--global

List the URL map for the existing Apigee GCLB

gcloud compute url-maps list -project $PROJECT_ID

Pick up the correct URL map name used for Apigee load balancing

gcloudcomputeurl-mapsexportAPIGEE_URL_MAP_NAME-project$PROJECT_ID

Create a load balancing URL map YAML file

If you already have an existing URL map, merge this configuration into that. Otherwise, create a YAML file at/tmp/apigee-map.yaml with this configuration.

defaultService:projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_1name:matcher1routeRules:-matchRules:-headerMatches:-headerName:Content-TypeprefixMatch:application/grpcprefixMatch:/priority:100routeAction:weightedBackendServices:-backendService:projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_2weight:100

Apply the new YAML for gRPC routing

gcloudcomputeurl-mapsimportAPIGEE_URL_MAP_NAME\--source/tmp/apigee-map.yaml  \--global-project$PROJECT_ID

Adding security

Proxy security is achieved by adding a policy to your proxy. For more information on policies, seeWhat's a policy. For more information on security, seeSecuring a proxy.

To add a security policy to your proxy:

Apigee in Cloud console

  1. Create a proxy as described inCreating an API proxy.
  2. Add a security policy as described in one of the sections listed inSecuring a proxy. The most common security policies used areAPI keys andOAuth2.

Classic Apigee UI

On theCommon policies page of theCreate Proxy wizard, select the type of security authorization you wish to add. The following table summarizes the available options:

Security authorizationDescription
API KeyAdds 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.0Adds 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, seeOAuth.
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 adding the CORS policy to therequest PreFlow of the ProxyEndpoint.

For more detailed information about CORS support, including adding CORS preflight support to a proxy, seeAdding CORS support to an API proxy.

Adding Quotas

Quotas protect your backend service from high traffic underQuota. SeeQuotas. (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, seeOpenAPI Initiative.

AnOpenAPI 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, seeOpenAPI spec for the helloworld sample.

openapi:3.0.0info:description:OpenAPISpecificationfortheApigeemocktargetserviceendpoint.version:1.0.0title:MockTargetAPIpaths:/:get:summary:ViewpersonalizedgreetingoperationId:Viewapersonalizedgreetingdescription:Viewapersonalizedgreetingforthespecifiedorguestuser.parameters:-name:userin:querydescription:Yourusername.required:falseschema:type:stringresponses:"200":description:Success/help:get:summary:GethelpoperationId:Gethelpdescription:ViewhelpinformationaboutavailableresourcesinHTMLformat.responses:"200":description:Success...

Through theCreate 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 theCreate Proxy wizard, clickUse OpenAPI Spec and follow the wizard to create a reverse or no target proxy from an OpenAPI Specification. For details, seeCreating an API proxy from an OpenAPI Specification.

Creating a new revision of an API proxy

To create a new revision of an API proxy, perform the following steps:

  1. Open the Apigee UI.

    2. Apigee in Cloud console

    In the Google Cloud console, go to theProxy development> API proxies page.

    Go to API proxies

    Classic Apigee UI

    1. Sign in to theApigee UI.
    2. In the navigation bar, selectDevelop > API Proxies.
  2. Click the API proxy in the list that you want to copy.

  3. Click theDevelop tab.

  4. Select theSave button and selectSave 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 inImporting an API proxy from an API proxy bundle previously in this section. For more information, seeDownload API proxies.

Creating an API proxy using the API

To create an API proxy using the API, seeCreating an API proxy.

About no target proxies

No target proxies in Apigee are useful when you want to process requests within Apigee itself without forwarding them to a backend service. It's important to understand when this approach is appropriate.

Common use cases

  • Interacting with Apigee-managed data:A no target proxy is useful in cases where you only need to interact with Apigee-managed data, such as data stored in akey-value map (KVM) or theApigee cache. For example, you can use a no-target proxy to retrieve data, such as user session data or configuration data, from the KVM. In this case, there's no need to call a backend service. All that's needed is aKeyValueMapOperations policy in the proxy flow. For another example, you might want the caller to request that a cache be flushed. You cando this by invoking theInvalidateCache policy, without any need to connect to a target.
  • Using mock APIs: You can create mock APIs to simulate API behavior before the backend implementation is complete to enable frontend development to progress independently. To learnmore about creating mock APIs, seeOpenAPI Mock API Proxy.
  • Token management: Apigee can issue OAuthV2 tokens, and that is usually done via a no-target proxy.
  • Testing policy behavior: A no-target proxy can be useful when you want to try out Apigee policies to test their behavior.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.