Build a simple API proxy

Apigee Edge 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 only need to provide the network address for the backend service, along with some information that Edge 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.

Watch this video for an overview of the process of creating an API proxy.

Create an API proxy using the UI

The easiest way to create an API proxy is using the Create Proxy wizard.

Access the Create Proxy wizard using the Edge UI or Classic Edge UI, as described in the following sections.

Edge

To access the Create Proxy wizard:

  1. Sign in to apigee.com/edge.
  2. Select Develop > API Proxies in the left navigation bar.
  3. Click +Proxy

Classic Edge

To access the Create Proxy wizard:

  1. Sign in to enterprise.apigee.com.
  2. Select APIs > API Proxies in the top navigation bar.
  3. Click + API Proxy

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

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

The first page of the wizard enables you 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 UseOpenAPI to generate the proxy from a valid OpenAPI specification. For more informations on this option, see Using OpenAPI Specifications to generate proxies later in this section.

Node.js App

An API proxy that routes to a Node.js backend target running on Edge. See Get started with Node.js on Apigee Edge.

Click UseOpenAPI to generate the proxy from a valid OpenAPI specification. For more informations on this option, see Using OpenAPI Specifications to generate proxies later in this section.

SOAP service An API proxy generated from a WSDL file. See Exposing a SOAP-based web service as an API proxy.
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 UseOpenAPI to generate the proxy from a valid OpenAPI specification. For more informations on this option, see Using OpenAPI Specifications to generate proxies later in this section.

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 describe how to create an API proxy using each source.

Creating a reverse proxy for an HTTP service

Edge generates reverse proxies based on two pieces of 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).

  1. Access the Create Proxy wizard, as described in Creating an API proxy using the UI previously in this section.
  2. In the Build a Proxy wizard, select Reverse proxy (most common). To generate the proxy from an existing, valid OpenAPI spec, click Use OpenAPI. For details on this option, see Using OpenAPI Specifications to generate proxies below.
  3. Click Next.
  4. On the Details page of the wizard, enter the following information.
    Field Description
    Proxy Name The name displayed for your API.
    Proxy Base Path

    The Proxy Base Path is a URI fragment after the http(s)://[host] address of your API proxy. Edge uses the Base Path URI to match and route incoming request messages to the proper API proxy.

    Note: For Apigee's recommendations on API versioning, see Versioning in the Web API Design: The Missing Link e-book.

    After the base path are any additional resource URLs. Here's the full URL structure that clients will use to call your API proxy:

    https://[host]/base_path/conditional_flow_path

    Note: The base path must be unique. If you later edit this proxy and set its base path to be the same as another API proxy, this API proxy is automatically undeployed when you save it. You must edit the base path before you can redeploy it.

    Using a wildcard in base paths

    You can use one or more /*/ wildcards in API proxy base paths to future-proof your 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.

    Note: The Proxy Base Path defaults to the value specified for Proxy Name converted to all lower case unless you explicitly edit the content in the Proxy Base Path field.

    Existing API The URL that the API Platform invokes on behalf of apps that call your API through the API proxy URL.
    Description The description of the API.
  5. On the Security page of the wizard, configure the following:
  6. On the Virtual Hosts page of the wizard, select the virtual hosts the API proxy will bind to when deployed. For more information, see About virtual hosts.
  7. Select the deployment environment(s) and click Build and Deploy
    An acknowledgment is sent confirming that your new API proxy was successfully created and deployed in the selected environment.
  8. Click View the <proxy name> proxy in the editor to display the details page for the API proxy.

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 Edge you can maintain them in a source-control system, and then import them into Edge for testing and deployment.

Watch this video to learn how to create and import an API proxy from an API proxy bundle.

To import API proxies from an API proxy bundle:

  1. Access the Create Proxy wizard, as described in Creating an API proxy using the UI previously in this section.
  2. In the Build a Proxy wizard, select Proxy bundle.
  3. Click Next.
  4. On the Details page in the proxy wizard, enter the following information.

    Field Description
    ZIP Bundle Click Choose File and navigate to the ZIP file containing the API proxy configuration.
    Proxy Name The name displayed for your API.
  5. Review the build information and click Build.
    If successful, a message is displayed and Edge automatically deploys the imported API proxy to the selected environment in your organization. The API exposed by the API proxy is available to be invoked.
  6. Click View the <proxy name> proxy in the editor to display the details page for the API proxy.
  7. To deploy the proxy, click the Deployment drop-down, select the environment you want to deploy to, and respond to the prompt.

Exposing a SOAP-based web service as an API proxy

In the Build a Proxy wizard, select Soap Service, and follow the wizard to create a pass-through or REST-based proxy for a SOAP service.

For details, see Exposing a SOAP service as an API proxy.

Adding security

On the Security page of the Build a Proxy wizard, select the type of authentication you wish to add. The following table summarizes the available options:

Field Description
Pass through (none) No authorization required. Requests are passed to the backend without any security checks on Apigee Edge.
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 Edge automatically adds two 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.

When you select API key or OAuth 2.0 authentication, the following additional selections are available:

Field Description
Impose Quota per Developer If enabled, adds a Quota policy that limits the number of request messages that can be submitted to your API proxy by an individual app over an interval of time.
Publish API Product If enabled, automatically generate an API product when you build the new API proxy. The autogenerated API product will be created with an association to the new API proxy.For information about products, see What is an API product?

Adding support for CORS

CORS (Cross-origin resource sharing) 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 to your API by selecting Add CORS headers in the Security page of the Add a 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.

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, Node.js, 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 about the Open API Initiative, see https://openapis.org.

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 such elements of an API 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.

Here's a fragment from an OpenAPI Specification that describes Apigee's mock target service, http://mocktarget.apigee.net. For more information, see https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

swagger: '2.0'
info:
  description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
  version: 1.0.0
  title: Mock Target API
host: mocktarget.apigee.net
schemes:
  - http
  - https
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      produces:
        - text/plain
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          type: string
      responses:
        '200':
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      produces:
        - text/html
      responses:
        '200':
          description: Success
...

Through the Build a 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 Edge UI to further develop it by adding policies, implementing custom code, and so on -- just like any Edge 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.

Watch this video to learn how to create an API proxy from an OpenAPI Specification.

To create an API proxy from an OpenAPI Specification:

  1. Access the Create Proxy wizard, as described in Creating an API proxy using the UI previously in this section.
  2. In the Build a Proxy wizard, select the type of proxy you wish to create. OpenAPI is supported for reverse, Node.js, and no target proxies.
  3. Click Use OpenAPI.
  4. In the dialog, enter a URL pointing to an existing, valid OpenAPI Specification. For example, you can try this URL to test it out:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  5. Click Apply.
    Edge reads the spec, and uses it to generate the proxy.
  6. Click Next.

  7. The Details page in the Build a Proxy wizard displays. The fields are pre-populated using values defined in the OpenAPI Specification. For example, if you selected reverse proxy:
    Build a Proxy Details page. Details are described below figure.
    The following table describes the default field values that are pre-populated using properties in the OpenAPI Specification. An excerpt of the OpenAPI Specification illustrating the properties used is shown following the table.
    Field Description Default
    Proxy Name Name of the API proxy. For example: Mock-Target-API. title property from the OpenAPI Specification with spaces replaced by dashes
    Proxy Base Path

    Path component that uniquely identifies this API proxy within the organization. The public-facing URL of this API proxy is comprised of your organization name, an environment where this API proxy is deployed, and this Proxy Base Path. For example: https://myorg-test.apigee.net/mock-target-api

    Note: The Proxy Base Path defaults to the value specified for Proxy Name converted to all lower case unless you explicitly edit the content in the Proxy Base Path field.

    Proxy Name field content converted to all lower case
    Existing API

    Note: Field is valid for reverse proxies only.

    Target URL invoked on behalf of this API proxy. Any URL that is accessible over the open Internet can be used. For example: https://mocktarget.apigee.net

    Properties in OpenAPI Specification are combined to create target URL:
    • http:// or https:// (depending on the schemes property)
    • host property
    • basePath property (if specified)
    Description Description of the API proxy. description property

    The following provides an excerpt from the OpenAPI Specification highlighting the properties that are used to pre-populate the fields.

    swagger: '2.0'
    info:
      description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
      version: 1.0.0
      title: Mock Target API
    host: mocktarget.apigee.net
    schemes:
      - http
      - https
    ...
      
    
  8. Click Next.
  9. On the Flows page, select the operations for which you want to generate conditional flows. Conditional flows are generated automatically from the operations that are defined within the paths object in the OpenAPI Specification. Conditional flows tell Edge, "When you see this, perform this logic." For more information, see Controlling how a proxy executes with flows. For example:
    Build a Proxy Flows page showing the path, verb, operation ID, and summary for each of the operations in the Mock Target API. All are seleted except for /help.
  10. On the Security page of the wizard, configure the following:
  11. On the Virtual Hosts page of the wizard, select the virtual hosts the API proxy will bind to when deployed. For more information, see About virtual hosts.
  12. Select the deployment environment(s) and click Build and Deploy
    An acknowledgment is sent confirming that your new API proxy was successfully created and deployed in the selected environment.
  13. Click View the <proxy name> proxy in the editor to display the details page for the API proxy.

The following figure shows the Develop view in the Edge UI for the Mock-Target-API proxy. (Note that a conditional flow is not automatically generated for the Get help operation.)

Develop view in the Edge UI for the Mock-Target-API proxy.

Updating the flows in an API proxy using an OpenAPI Specification

After you create an API proxy from an OpenAPI Specification, if you modify the specification to add additional resource paths you can use the specification to add the associated conditional flows to the API proxy.

>To update the flows in an API proxy using an OpenAPI Specification:

  1. Add the new resource paths to the OpenAPI Specification. See Editing an existing OpenAPI Specification.
  2. Open the API Proxy in the UI and click the Develop tab.
  3. In the Navigator, click + next to the Proxy endpoint that you want to update.
    The New Conditional Flow dialog box opens.
  4. Click From OpenAPI if it is not already selected.
    If there are resources in the OpenAPI Specification that do not have a corresponding conditional flow in the API proxy, they are listed in the dialog, as shown in the following figure. Resources that are not respresented as flows in the current API proxy. This example includes /loveapis, /ip, /json, and /xml.
  5. Select each of the resources for which you want to add a conditional flow.
  6. Click Add.

The conditional flows are added to your API proxy.

Creating a new revision of an API proxy

Create a new revision of an API proxy using the Edge UI or Classic Edge UI, as described in the following sections.

Edge

To create a new revision of an API proxy:

  1. Sign in to apigee.com/edge.
  2. Select Develop > API Proxies in the left navigation bar.
  3. Click the API proxy in the list that you want to copy.
  4. Select Project > Save as New Revision.

Classic Edge

To create a new revision of an API proxy:

  1. Sign in to enterprise.apigee.com.
  2. Select APIs > API Proxies in the top navigation bar.
  3. Click the API proxy in the list that you want to copy.
  4. Select Project > Save as New Revision.

Copying an API proxy

Copy an existing API proxy to a new API proxy using the Edge UI or Classic Edge UI, as described in the following sections.

Edge

To copy an API proxy:

  1. Sign in to apigee.com/edge.
  2. Select Develop > API Proxies in the left navigation bar.
  3. Click the API proxy in the list that you want to copy.
  4. Select Project > Save as New API Proxy.
  5. In the Save as New Proxy dialog, enter the name of the new API proxy.
  6. Click Add.

Classic Edge

To copy an API proxy:

  1. Sign in to enterprise.apigee.com.
  2. Select APIs > API Proxies in the top navigation bar.
  3. Click the API proxy in the list that you want to copy.
  4. Select Project > Save as New API Proxy.
  5. In the Save as New Proxy dialog, enter the name of the new API proxy.
  6. Click Add.

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 the API Proxies.