Creating an API proxy from an OpenAPI Specification

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

What you'll learn

In this tutorial, you'll learn to:

  • Create an Apigee API proxy from an OpenAPI Specification.
  • Call the API proxy using cURL.
  • Add a policy to a conditional flow.
  • Test the policy invocation using cURL.

You'll learn how to create an Apigee API proxy from an OpenAPI Specification using the Apigee UI. When you call the API proxy with an HTTP client, such as cURL, the API proxy sends the request to the Apigee mock target service.

About the Open API Initiative

Open API Initiative

"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, seeThe OpenAPI Specification.

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

About the Apigee mock target service

The Apigee mock target service used in this tutorial is hosted at Apigee and returns simple data. It requires no API key or access token. In fact, you can access it in a web browser. Try it out by clicking the following:

http://mocktarget.apigee.net

The target service returns the greetingHello, guest!

For information about the full set of APIs the mock target service supports, seeApigee Sample APIs

What you'll need

  • Before you begin, you must complete the steps inOverview and prerequisites.
  • An OpenAPI Specification. In this tutorial, you'll use themocktarget.yaml OpenAPI Specification which describes Apigee's mock target service,http://mocktarget.apigee.net. For more information, see apigee/api-platform-samples.
  • cURL installed on your machine to make API calls from the command line; or a web browser.

Create the API proxy

To create the API proxy from an OpenAPI Specification:

Apigee in Cloud console

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

    Go to API proxies

  2. In theAPI Proxies pane, click+ Create.
  3. In theCreate a proxy pane, underProxy template> OpenAPI spec template, selectReverse proxy (Most common).
  4. Navigate to the following URL in your web browser:
    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  5. Right-click on the displayed code and selectSave As.
  6. ClickSave to save themocktarget3.0.yaml at the desired location.
  7. In theOpenAPI specs field, click theBrowse button.
  8. Navigate to themocktarget3.0.yaml file and clickOpen.
  9. ClickNext.
  10. TheProxy details step of theCreate Proxy wizard automatically populates its fields with values extracted directly from the OpenAPI Specification.

    11. The following table describes the default values that are pre-populated using the OpenAPI Specification:

    FieldDescriptionDefault
    Proxy nameName of the API proxy. For example:Mock-Target-API.title property from the OpenAPI Specification with spaces replaced by dashes
    Base pathPath component that uniquely identifies this API proxy within the organization. The public-facing URL of this API proxy is comprised of your external or internal domain name and this base path. For example:http://apitest.acme.com/mock-target-apiName field content converted to all lower case
    DescriptionDescription of the API proxy.description property from the OpenAPI Specification
    Target (Existing API)Target URL invoked on behalf of this API proxy. Any URL that is accessible over the open Internet can be used. For example:http://mocktarget.apigee.netservers property from the OpenAPI Specification

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

          openapi: 3.0.0      info:description: OpenAPI Specification for the Apigee mock target service endpoint.        version: 1.0.0title: Mock Target API      paths:        /:          get:            summary: View personalized greeting            operationId: View a personalized greeting            description: View a personalized greeting for the specified or guest user.            parameters:              - name: user                in: query                description: Your user name.                required: false                schema:                  type: string            responses:              "200":                description: Success      ...servers:        - url: http://mocktarget.apigee.net        - url: https://mocktarget.apigee.net      ...
  11. In theProxy details step, edit theDescription field as follows:
    API proxy for the Apigee mock target service endpoint.
  12. ClickNext.
  13. In theFlows step, make sure all operations are selected.Tip: Conditional flows are generated automatically from the operations that are defined within thepaths object in the OpenAPI Specification. Conditional flows tell Apigee, "When you see this, perform this logic." For example, when an API call is aGET on the/xml resource (the condition), transform the response to JSON (through a policy attached to the conditional flow). Only one flow executes per transaction—the first flow whose condition evaluates to true.
  14. ClickNext.
  15. In theDeploy step, select one or more environments, and clickOK.
  16. ClickCreate.

Classic Apigee UI

  1. SelectDevelop > API Proxies and in theProxies pane, select the environment for the proxy.
  2. ClickAPI Proxies in the main window.

    Alternatively, you can selectDevelop > API Proxies in the left navigation bar.

    Click API Proxies on landing page

  3. ClickCreate New.

    Add API proxy

  4. In theCreate Proxy wizard, clickUse OpenAPI Spec for theReverse proxy (most common) template.

    Build a Proxy type
  5. ClickURL and enter the following information:

    OpenAPI Spec URL: Path to the raw content on GitHub for the OpenAPI Specification in theURL field:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  6. ClickSelect.

    TheProxy details page in theCreate Proxy wizard displays. The fields are pre-populated using values defined in the OpenAPI Specification as shown in the following figure:

    The following table describes the default values that are pre-populated using the OpenAPI Specification:

    FieldDescriptionDefault
    NameName of the API proxy. For example:Mock-Target-API.title property from the OpenAPI Specification with spaces replaced by dashes
    Base pathPath component that uniquely identifies this API proxy within the organization. The public-facing URL of this API proxy is comprised of your external or internal domain name and this base path. For example:http://apitest.acme.com/mock-target-apiName field content converted to all lower case
    DescriptionDescription of the API proxy.description property from the OpenAPI Specification
    Target (Existing API)Target URL invoked on behalf of this API proxy. Any URL that is accessible over the open Internet can be used. For example:http://mocktarget.apigee.netservers property from the OpenAPI Specification

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

    openapi: 3.0.0info:description: OpenAPI Specification for the Apigee mock target service endpoint.  version: 1.0.0title: Mock Target APIpaths:  /:    get:      summary: View personalized greeting      operationId: View a personalized greeting      description: View a personalized greeting for the specified or guest user.      parameters:        - name: user          in: query          description: Your user name.          required: false          schema:            type: string      responses:        "200":          description: Success...servers:  - url: http://mocktarget.apigee.net  - url: https://mocktarget.apigee.net...
  7. In theProxy details page, edit theDescription field as follows:
    API proxy for the Apigee mock target service endpoint.
  8. ClickNext.
  9. On theCommon policies page, underSecurity: Authorization ensure thatPass through (no authorization) is selected, and clickNext:

    Pass through (no authorization) selected on the Common policies page

  10. On theFlows page, make sure all operations are selected.Tip: Conditional flows are generated automatically from the operations that are defined within thepaths object in the OpenAPI Specification. Conditional flows tell Apigee, "When you see this, perform this logic." For example, when an API call is aGET on the/xml resource (the condition), transform the response to JSON (through a policy attached to the conditional flow). Only one flow executes per transaction—the first flow whose condition evaluates to true.Build a Proxy Flows
  11. ClickNext.
  12. On theSummary page, make sure an environment is selected underOptional Deployment and clickCreate and deploy:

    Apigee creates your new API proxy and deploys it to your environment:

  13. ClickEdit proxy to display theOverview page for the API proxy.
Congratulations! You've created an API proxy from an OpenAPI Specification. Next you'll test it to see how it works.

Add an XML to JSON policy

Next, you'll add the XML to JSON policy to theView XML Response conditional flow that was generated automatically when you created the API proxy from the OpenAPI Specification. The policy will convert the target's XML response to a JSON response.

First, call the API so that you can compare the results with those received after you add the policy. In a terminal window execute the following cURL command. You're calling the target service's/xml resource, which natively returns a simple block of XML.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

whereYOUR ENV_GROUP_HOSTNAME is the environment group hostname. See Find the environment group hostname.

Response

You should see the following response:

<root>   <city>San Jose</city>   <firstName>John</firstName>   <lastName>Doe</lastName>   <state>CA</state> </root>

Now let's do something that converts the XML response to JSON. Add the XML to JSON policy to the View XML Response conditional flow in the API proxy.

Apigee in Cloud console

  1. Click theDevelop tab in theMock-Target-API Overview page in the Apigee UI.

    2. Select View XML Response

  2. In the left-hand pane, underProxy Endpoints > default, click theView XML Response conditional flow.
  3. In the left-hand pane, click the+ button in thePolicies row.

  4. In theCreate policy dialog, click in theSelect policy type field, scroll down toMediation, and selectXMLToJSON. Keep the default values forDisplay Name andName.

  5. ClickCreate to create the policy.

  6. Click the+ button next to theView XML response flow in theResponse.

    Select +Step

  7. In theAdd Policy Step dialog, click in theSelect existing policy field and selectXML to JSON-1.

  8. ClickAdd. The XML to JSON policy is applied to the response.

    XML to JSON policy in flow

    To view the code for theView XML Response conditional flow, clickSwitch To Code Editor.

  9. ClickSave.

Classic Apigee UI

  1. Click theDevelop tab in theMock-Target-API Overview page in the Apigee UI.

    Developer tab

  2. In the left Navigator pane, underProxy Endpoints > default, click theView XML Response conditional flow.

    Select View XML Response

  3. Click the bottom+Step button, corresponding to theResponse for the flow.

    Select +Step

    TheAdd Step dialog opens to display a categorized list of all the policies that you can add.

  4. Scroll to theMediation category and selectXML to JSON.

    Add Step dialog
  5. Keep the default values forDisplay Name andName.

  6. ClickAdd. The XML to JSON policy is applied to the response.

    XML to JSON policy in flow
  7. ClickSave.

Now that you've added the policy, call the API again using cURL. Notice that you're still calling the same/xml resource. The target service still returns its block of XML, but now the policy in the API proxy will convert the response to JSON. Make this call:

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

whereYOUR ENV_GROUP_HOSTNAME is the environment group hostname. See Find the environment group hostname.

Note that the XML response is converted to JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}
Congratulations! You have successfully tested the execution of a policy added to a conditional flow.

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-17 UTC.