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.

Before you begin: Familiarize yourself with the concepts described in the following topics:

• Understanding APIs and API proxies
• Key points of API proxy development

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 .

     

   • 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:

   Type	Description
   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.

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 .

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

Note: Before adding multiple proxy endpoints, review the following topic Antipattern: Define multiple ProxyEndpoints in an API proxy.

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 , and select Create proxy endpoint:
     • apiproxy-name proxy bundle
     • apiproxy-name/apiproxy
   • Position your cursor over the apiproxy-name/apiproxy/proxies folder and click .

   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.

   Field	Description
   Proxy endpoint name	Name used to identify the proxy endpoint.
   API proxy base path	Part 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 endpoint	Select 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:

• Controlling how a proxy executes with flows
• Determining the URL of the API proxy endpoint
• Adding features using policies
• Managing resources
• ProxyEndpoint configuration
• Flow configuration reference
• Endpoint properties reference

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.

Note: An API proxy does not need a target endpoint. Proxy endpoints can be configured to call URLs directly. An API proxy with no target endpoints usually contains a proxy endpoint that either directly calls a backend service or is configured to call a service using Java or JavaScript.

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 , and select Create target endpoint:
     • apiproxy-name proxy bundle
     • apiproxy-name/apiproxy
   • Position your cursor over the apiproxy-name/apiproxy/targets folder and click .

   The Create target endpoint wizard opens.

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

   Type	Steps
   External HTTP(s) target	To define an external HTTP(s) target: Select HTTP(s) target. Enter the name of the target endpoint in Target endpoint name. 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: Select Proxy chaining. Enter the name of the target endpoint in Target endpoint name. Select an API proxy. 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: Select Load balanced target. 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.

• Load balancing across backend servers
• Controlling how a proxy executes with flows
• Chaining API proxies together
• Determining the URL of the target endpoint
• Adding features using policies
• Managing resources
• TargetEndpoint configuration
• Flow configuration reference
• Endpoint properties reference