Developing API proxies

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Expose APIs on Apigee by implementing API proxies. API proxies decouple the app-facing API from your backend services, shielding those apps from backend code changes.

Develop your API proxies using Apigee in Cloud Code as described in the following sections. See also Managing folders and files in an Apigee workspace.

Creating an API proxy

To create an API proxy using Apigee in Cloud Code, make sure you've created a local development workspace and then:

  1. Perform one of the following actions:

    • In your workspace, position your cursor over the apiproxies folder and click Create API proxy icon.

      + displays when you position the cursor over apiproxies folder

    • Select View > Command Palette to open the Command palette and select Cloud Code: Create Apigee proxy bundle.

    The Create proxy wizard opens.

  2. Select one of the following options:

    TypeDescription
    Access token-based authentication

    Adds OAuth 2.0 based authentication to your API proxy. Apigee automatically adds the following policies to your API proxy:

    • Quota to manage quota on the proxy.
    • AssignMessage to strip the API key, supplied in the API call as a query parameter, from the request forwarded to the backend server.
    • OAuthV2 as the authentication method.
    API key-based authentication

    An API proxy that uses simple API key verification. Apigee automatically adds the following policies to your API proxy:

    • Quota to manage quota on the proxy.
    • VerifyAPIKey to validate API keys presented by requesting apps.
    • AssignMessage to strip the API key, supplied in the API call as a query parameter, from the request forwarded to the backend server.
    Echo request

    An API proxy that echos requests. There is no target/API backend for this proxy type and no authentication. You are not prompted to specify a URL for the backend service (Target (Existing API)) and the default target endpoint configuration is not included.

    Simple reverse proxy

    An API proxy that passes through requests to a backend target. It does not include authentication, so requests are passed to the backend without any security checks.

    OpenAPI 3.0 spec

    Create a proxy by loading an existing OpenAPI 3.0 spec. For more information, see OpenAPI Initiative.

  3. See API proxy primary fields for information on the fields, such as the base path, needed to create each proxy type. Respond to each of the prompts and press Enter to confirm and proceed, or Esc to cancel the wizard.

After you complete the steps in the wizard, the new apiproxy-name folder is added under apiproxies in the Apigee section. Each API proxy folder is structured as described in API proxy configuration directory structure.

The following provides an example of the default configuration created for a API proxy created with type API key-based authentication.

The folder structure of an API key-based authentication proxy

For a description of the default configuration, see Exploring the default API proxy configuration.

Exploring the default API proxy configuration

The following table summarizes the contents included in the default configuration when you create an API proxy based on the API proxy type and authentication options selected.

Configuration file
Simple reverse proxy
Echo request
Access token (OAuthV2) authentication
API key authentication
proxies/default.xml
Default proxy endpoint configuration.
targets/default.xml
Default target endpoint configuration.
 
impose-quota.xml
Quota policy to define a default quota.		  
remove-header-authorization.xml
AssignMessage policy to remove the Authorization header that is passed for authentication.		  
 
remove-query-param-apikey.xml
AssignMessage policy to remove the apikey query parameter that is passed for authentication.		   
verify-api-key.xml
VerifyAPIKey policy to enforce the verification of API keys.		   
verify-oauth-v2-access-token.xml
OAuthV2 policy to validate OAuth V2 access tokens.		  
 

Uploading an API proxy bundle

To upload an API proxy bundle to Apigee in Cloud Code:

  1. Perform one of the following actions:

    • In your Apigee workspace, position your cursor over the apiproxies folder and click Import API proxy bundle icon.

    • Select View > Command Palette to open the Command palette and select Cloud Code: Import Apigee proxy bundle.

  2. Navigate to the API proxy bundle that you want to upload and click Select. The API proxy bundle must be structured as described in API proxy configuration directory structure.

  3. (Optional) By default, the name of the zip file minus its extension is used for the name of the API proxy. If this name is not unique, you are prompted to enter a unique name.

The uploaded apiproxy-name folder is added under apiproxies in your workspace.

Managing proxy endpoints

As described in What is an API proxy?, a proxy endpoint (ProxyEndpoint) defines the way client apps consume your APIs. You configure the proxy endpoint to define the URL of your API proxy. The proxy endpoint also determines whether apps access the API proxy over HTTP or HTTPS. You can attach policies to the proxy endpoint to enforce security, quota checks, and other types of access control and rate-limiting.

Create and configure proxy endpoints as described in the following sections.

Creating proxy endpoints

When you create an API proxy, a default proxy endpoint is added to the API proxy configuration. For more information, see Exploring the default API proxy configuration. You can create additional proxy endpoints, as required.

To create a proxy endpoint using Apigee in Cloud Code:

  1. In your Apigee workspace, perform one of the following actions:

    • Position your cursor over one of the following folders, click Create proxy endpoint icon, and select Create proxy endpoint:
      • apiproxy-name proxy bundle
      • apiproxy-name/apiproxy
    • Position your cursor over the apiproxy-name/apiproxy/proxies folder and click Create proxy endpoint icon.

    The Create proxy endpoint wizard opens.

  2. Enter the values for the next set of prompts. Press Enter after each to confirm and proceed or Esc to cancel.

    FieldDescription
    Proxy endpoint nameName used to identify the proxy endpoint.
    API proxy base pathPart of the URL used to make requests to your API. Apigee uses the URL to match and route incoming requests to the proper API proxy.
    Target endpointSelect either no target or default. See ProxyEndpoint configuration elements for information.

The endpoint is created and added to the apiproxy-name/apiproxy/proxies folder in the Apigee section and opened in the editor. Configure the proxy endpoint, as described in the following section.

Configuring proxy endpoints

To configure proxy endpoints, refer to the following sections:

Managing target endpoints

As described in What is an API proxy?, a target endpoint (TargetEndpoint) defines the way the API proxy interacts with your backend services. You configure the target endpoint to forward requests to the proper backend service, and define any security settings, HTTP or HTTPS protocol, and other connection information. You can attach policies to the target endpoint to ensure that response messages are properly formatted for the app that made the initial request.

Create and configure target endpoints as described in this section.

Creating target endpoints

When you create a reverse API proxy, a default target endpoint is added to the API proxy configuration. When creating an API proxy with no backend target, only the default proxy endpoint is added to the API proxy configuration, no target endpoint is added. For more information, see Exploring the default API proxy configuration.

Create target endpoints, as required.

To create a target endpoint using Apigee in Cloud Code:

  1. In your Apigee workspace, perform one of the following actions:

    • Position your cursor over one of the following folders, click Create target endpoint icon, and select Create target endpoint:
      • apiproxy-name proxy bundle
      • apiproxy-name/apiproxy
    • Position your cursor over the apiproxy-name/apiproxy/targets folder and click Create target endpoint icon.

    The Create target endpoint wizard opens.

  2. Perform the following steps based on the type of target endpoint you want to create:

    TypeSteps
    External HTTP(s) target

    To define an external HTTP(s) target:

    1. Select HTTP(s) target.
    2. Enter the name of the target endpoint in Target endpoint name.
    3. Enter the URL of the backend service that this target endpoint invokes in Backend target URL.

    For more information, see Determining the URL of the target endpoint.

    Proxy chaining

    To define a locally deployed API proxy as your target:

    1. Select Proxy chaining.
    2. Enter the name of the target endpoint in Target endpoint name.
    3. Select an API proxy.
    4. Select the proxy endpoint.

    For more information, see Chaining proxies together.

    Load balanced target

    To define a load balanced target using target servers defined in the environment:

    1. Select Load balanced target.
    2. Enter the name of the target endpoint in Target endpoint name.

    For more information, see Configuring a TargetEndpoint to load balance across named TargetServers.

The target endpoint is created and added to the apiproxy-name/apiproxy/targets folder and opened in the editor. Configure the target endpoint, as described in the following section.

Configuring target endpoints

Configure target endpoints, as described in the following topics.