Creating an Edge API proxy to manage client calls to your Cloud Foundry application

This tutorial describes how to create an Edge API proxy and use cf command-line commands to create an API proxy and bind a Cloud Foundry application's route to it.

In this tutorial, you'll use CLI commands place an Apigee Edge proxy in front of an existing Cloud Foundry application.

Install the Apigee service broker

Install the service broker using one of the following set of instructions. Once you have it installed, you can return here to continue with the tutorial.

Push the Cloud Foundry sample app

Start by adding a Cloud Foundry sample app to your CF instance. This will be the CF app for which an Apigee Edge API proxy will manage requests. These steps use a sample available on the Apigee GitHub repository.

  1. Clone the Apigee Pivotal Cloud Foundry sample app at the following URL:

    For example, from the command-line you can clone the repository this way:

    git clone 
  2. In your local repository, cd to the sample-api directory.
  3. In the sample-api directory, open manifest.yml.
  4. Edit manifest.yml to change the name and host properties to something specific for you, such as your Pivotal org name plus the -api-apigee.

    For example, you might end up with the file looking like this:

        - name: sample-api 
        memory: 128M 
        instances: 1 
        host: sample-api-apigee 
        path: . 
        buildpack: nodejs_buildpack
  5. Save the edited file.
  6. In the sample-api directory, from the command line, log in to your Pivotal Cloud Foundry account.
    cf login -a <your.endpoint> -u <username> -o <organization> -s space 
  7. From within the sample-api directory, use the push command to push the Apigee Cloud Foundry sample app to your organization.
    cf push 
  8. Get the URL for the sample you pushed by running the apps command.
    cf apps

    Locate the name of the app you pushed, then find its URL in the urls column of the output.

  9. Using cURL, send a request to the app you just pushed.

    The console will display the app's response.

    {"hello":"hello from cf app"} 

Create an instance of the Apigee service

In these steps, you'll create an instance of the Apigee Edge service. Then you'll create a new API proxy and bind the service to Apigee Edge. That way, request to your Cloud Foundry app will be forwarded to the new API proxy for management.

  1. Use the cf marketplace command to get a list of services in the Cloud Foundry Marketplace. Use the list to confirm that the apigee-edge service broker is there, as in the following example output:
    $ cf marketplace
    Getting services from marketplace in org myorg / space myspace as admin...
    service          plans                     description
    KafkaService     ManyToMany                Kafka Service Broker for Pivotal Cloud Foundry
    apigee-edge      org, microgateway         Apigee Edge API Platform
    app-autoscaler   bronze, gold              Scales bound applications in response to load (beta)
    cloudflare       cloudflare-free           Give us five minutes and we’ll supercharge your website.
    hello            hi                        Friendly service that greets you
    p-mysql          100mb                     MySQL databases on demand
    p-rabbitmq       standard                  RabbitMQ is a robust and scalable high-performance multi-protocol messaging broker.
    p-redis          shared-vm, dedicated-vm   Redis service to provide a key-value store

    Notice that the apigee-edge service broker supports two service plans:

    • org -- Use this plan when you'll be proxying through Apigee Edge Cloud. Use this value for the tutorial.
    • microgateway -- Use this plan when you'll be proxying through Apigee Edge Microgateway.
  2. Specifying the org service plan, use create-service command to create an instance of the Apigee Edge service broker.

    The following example specifies the apigee-edge service, the org service plan, and gives apigee-service as a name for the newly created instance.

    cf create-service apigee-edge org apigee-service 
  3. Execute the cf service command to get information about the service you just created.
    $ cf service apigee-service
    Service instance: apigee-service
    Service: apigee-edge
    Bound apps:
    Plan: org
    Description: Apigee Edge API Platform
    Documentation url:
    Last Operation
    Status: create succeeded
    Started: 2016-10-27T20:47:43Z

Bind the CF app's route to the Apigee service

In this step, you bind the Cloud Foundry app's route (its address in Cloud Foundry) to the Apigee service instance you created. That way, requests to the app will be forwarded first to an Edge proxy. The bind-route-service command creates the proxy for you and binds the route to it.

  1. Using Apigee Edge scripts from the command line, get or update a token with which to authenticate with your Apigee Edge organization. You'll use this when binding the Apigee route service to your Cloud Foundry instance.

    Each call from Cloud Foundry to Apigee Edge requires authentication. By making a token available to the route service, you make it possible for the service to authenticate.

    You can create an authentication token by using command-line scripts available with Apigee Edge. If you don't have these already, you'll find instructions for getting them under "How to get OAuth2 tokens" at Using OAuth2 security with the Apigee Edge management API. Be sure that you have a directory at ~/.sso-cli before you run the script.

    • Using the get_token command from Apigee utility scripts, create a token. If prompted for your Apigee Edge username and password, enter those you use to log into your organization.

    The script will write the token to a file in your ~/.sso-cli directory.

    For more about get_token, see Using OAuth2 security with the Apigee Edge management API.

  2. Use the bind-route-service command (see the reference below) to create an Apigee Edge API proxy and bind your Cloud Foundry application to the proxy.

    This tells the Cloud Foundry Go router to redirect requests to the Apigee Edge proxy before sending them to the Cloud Foundry application.

    cf bind-route-service apigee-service --hostname sample-api-apigee \ 
        -c '{"org":"my_edge_org","env":"my_edge_env", 
        "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'", 
        "action":"proxy bind",

    You should see output such as the following:

    Binding route to service instance apigee-service in org apigee / space test as admin...

bind-route-service reference

Use the bind-route-service command to generate an API proxy on Apigee Edge and to bind the Apigee Cloud Foundry service to the proxy. The command this form (be sure to use quotes and command expansion, as shown here):

cf bind-route-service <your-app-domain> <service-instance> [--hostname <hostname>] \
-c '{"org":"<your edge org>","env":"<your edge env>",
    "bearer":"'<authentication-token-file>'" | "basic":"<encoded-username-password>" | "<username>:<password>",
    "action":"proxy"|"bind"|"proxy bind",

Parameters for the -c argument specify connection details:

Parameter Purpose Allowed Values
org Apigee Edge organization hosting the API proxy to be called Your organization (must be reachable via the authentication token specified in the bearer parameter)
env Apigee Edge environment to which the API proxy is (or will be) deployed Your environment.
bearer Path to a file containing an authentication token valid for your organization An authentication token, such as one generated with Apigee's get_token command. The broker does not store any data; it requires credentials and other parameters for each individual cf command. Instead of a bearer token, credentials can also be expressed as:
  • basic: standard HTTP Base-64 encoded username and password for Authorization: Basic. Note that this is not encrypted and easily converted to clear text. But a jumble of digits and letters may provide some protection in case of momentary exposure (but no better than if the password is already a jumble of digits, letters, and symbols)
  • username and password in clear text
action A value specifying whether to create or bind an API proxy proxy to generate an API proxy; bind to bind the service with the proxy; proxy bind to generate the proxy and bind with a single command.
protocol The protocol through which the proxy should be accessed by Cloud Foundry http or https; default is https.

Test the binding

Once you've bound the app's path to the Apigee service (creating an Apigee proxy in the process), you can try it out with the sample app you invoked earlier.

  1. Open the Apigee Edge management console.
  2. In the management console, under APIs > API proxies, locate the name of the proxy you just created with bind-route-service. It's likely to have a name that ends with your domain value, such as
  3. Click the new proxy's name to view its overview page.
  4. Click the Develop tab to view the proxy's code.

    Note that the bind-route-service command currently generates an API proxy whose target endpoint is reached via HTTP, rather than HTTPS. If you prefer to use HTTPS, be sure to change the protocol by editing the proxy using the following instructions.

    1. In the Navigator on the left, under Target Endpoints, locate the default endpoint.
    2. In the Code window in the middle, locate the HTTPTargetConnection element's URL child element.
    3. Change the URL element's value so that it specifies https rather than http.
    4. Click Save.
  5. Click the Trace tab, the click the Start Trace Session button.
  6. Back at the command line, run the cURL command you ran earlier -- the one that makes a request to the Cloud Foundry application you pushed, such as.

    As before, the console will display the app's response.

    {"hello":"hello from cf app"} 
  7. Return to the Apigee Edge management console to see that your request has now been routed through the Edge proxy you created.

The new proxy is just a pass-through. But it's ready for you or someone on your team to add policies to define security, traffic management, and more.

Unbinding the route service

The unbind command does not accept any parameters

cf unbind-route-service myapigee --hostname test-app

Uninstalling the service instance and broker

cf delete-service myapigee
cf delete-service-broker apigee-edge