You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/tutorials/create-api-proxy-openapi-spec). info
**What you'll learn**

In this tutorial, you'll learn to:

- Create an Edge 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.
In this tutorial, you'll learn how to create an Edge API proxy from an OpenAPI
Specification using the Apigee Edge management 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](https://docs.apigee.com/static/api-platform/images/OpenAPI_Pantone.png)](https://openapis.org)

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

**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](https://mocktarget.apigee.net)

The target service returns the greeting `Hello, guest!`

For information about the full set of APIs the mock target service supports, click on the
following:

[http://mocktarget.apigee.net/help](https://mocktarget.apigee.net/help)

## What you'll need

- An Apigee Edge account. If you don't have an account, you can sign up by following the instructions at [Creating an Apigee Edge
  account](https://docs.apigee.com/api-platform/get-started/creating-apigee-edge-account).
- An OpenAPI Specification. In this tutorial, you'll use the `mocktarget.yaml` OpenAPI Specification which 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`.
- [cURL](https://curl.haxx.se/) installed on your machine to make API calls from the command line; or a web browser.

## Create the API proxy

### Edge

To create the API proxy from an OpenAPI Specification using the Edge UI:

1. Sign in to <https://apigee.com/edge>.
2. Click API Proxies in the main window. Alternatively, you can select **Develop \> API Proxies** in the left navigation bar.

   ![Click API Proxies on landing page](https://docs.apigee.com/static/api-platform/images/tutorial_new_edge_apis_menu.png)
3. Click **+ Proxy** .  
   ![Add API proxy](https://docs.apigee.com/static/api-platform/images/tutorial_new_api_proxy_button.png)
4. In the Create Proxy wizard, click **Use OpenAPI Spec** for the **Reverse proxy (most common)** template.  
   ![Build a Proxy type](https://docs.apigee.com/static/api-platform/images/tutorial-proxy-type-v2.png)
5. Click **Import from URL** and enter the following information:
   - **OpenAPI Spec URL** : Path to the raw content on GitHub for the OpenAPI Specification in the **URL** field:

     ```
     https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
     ```
   - **Spec name** : Name for the OpenAPI Specification, such as **Mock Target** .


     This name is used to store the OpenAPI Specification in the spec store. See [Manage your specifications](https://docs.apigee.com/api-platform/publish/specs/manage-specs).
6. Click **Import** .

   The Details page in the Create Proxy wizard displays. The fields are pre-populated
   using values defined in the OpenAPI Specification, as shown in the following

   The following table describes the default 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 |
   |---|---|---|
   | **Name** | Name of the API proxy. For example: `Mock-Target-API`. | `title` property from the OpenAPI Specification with spaces replaced by dashes |
   | **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 base path. For example: `http://myorg-test.apigee.net/mock-target-api` | **Name** field content converted to all lower case |
   | **Description** | Description 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.net` | `servers` 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.0
     title: 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
   ...
   ```
7. Edit the **Description** field as follows: `API proxy for the Apigee
   mock target service endpoint.`
8. Click **Next**.
9. On the **Common policies** page, under Security: Authorization ensure that **Pass through (no authorization)** is selected, and click **Next** :

   ![Pass through (no authorization) selected on the Common policies page](https://docs.apigee.com/static/api-platform/images/mocktarget-passthrough.png)
10. On the Flows page, make sure all operations are selected.

    > [!IMPORTANT]
    > **Tip:** 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 example, when an API call is a GET 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](https://docs.apigee.com/static/api-platform/images/tutorial-build-proxy-flows-v3.png)
11. Click **Next**.
12. On the **Virtual hosts** page, select **default** and **secure** , and click **Next** .  
    ![default and secure selected on the Virtual hosts page](https://docs.apigee.com/static/api-platform/images/virtual-host-tutorial-v2.png)
13. On the **Summary** page, make sure the **Test** environment is selected under **Optional Deployment** and click **Create and
    deploy** :

    ![](https://docs.apigee.com/static/api-platform/images/mocktarget-summary.png)

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

    ![](https://docs.apigee.com/static/api-platform/images/mocktarget-proxy-done.png)
14. Click **Edit proxy** to display the Overview page for the API proxy.  
    ![Summary of Mock Target API proxy](https://docs.apigee.com/static/api-platform/images/tutorial-mock-target-overview-v5.png)

### Classic Edge (Private Cloud)

> [!NOTE]
> **Note:** The Classic Edge UI is available with Edge for Private Cloud only.

To create the API proxy from an OpenAPI Specification using the Classic Edge UI:

1. Sign in to <https://apigee.com/edge>.
2. Click API Proxies in the main window. Alternatively, you can select **Develop \> API Proxies** in the left navigation bar.

   ![](https://docs.apigee.com/static/api-platform/images/tutorial_new_edge_apis_menu.png)
3. Click **+ Proxy** .  
   ![Add API proxy](https://docs.apigee.com/static/api-platform/images/tutorial_new_api_proxy_button.png)
4. In the Create Proxy wizard, select **Reverse proxy (most common)** and click **Use OpenAPI** .  
   ![Build a Proxy type](https://docs.apigee.com/static/api-platform/images/tutorial-proxy-type.png)
5. Click **Import from a URL** , enter a name for the OpenAPI Specification, and enter the path to the raw content on GitHub for the OpenAPI Specification in the **URL** field:  

   `https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml`  
6. Click **Select**.
7. Click **Next** .

   The Details page in the Create Proxy wizard displays. The fields are pre-populated
   using values defined in the OpenAPI Specification, as shown in the following
   figure.
   ![Build a Proxy Details](https://docs.apigee.com/static/api-platform/images/tutorial-build-proxy-details-v2.png)

   The following table describes the default 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 base path. For example: `http://myorg-test.apigee.net/mock-target-api` | **Name** field content converted to all lower case |
   | **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.net` | `servers` property from the OpenAPI Specification |
   | **Description** | Description of the API proxy. | `description` 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.0
     title: 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
   ...
   ```
8. Edit the **Description** field as follows: `API proxy for the Apigee
   mock target service endpoint.`
9. Click **Next**.
10. On the Flows page, make sure all operations are selected.

    > [!IMPORTANT]
    > **Tip:** 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 example, when an API call is a GET 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](https://docs.apigee.com/static/api-platform/images/tutorial-build-proxy-flows-v2.png)
11. Click **Next**.
12. On the Security page, select **Pass through (none)** as the security option, and click **Next**.
13. On the Virtual Hosts page, make sure all virtual hosts are selected and click **Next**.
14. On the Build page, make sure the **test** environment is selected, and click **Build and Deploy**.
15. On the Summary page, you see an acknowledgement that your new API proxy was created successfully and deployed to your test environment.  
    ![Build a Proxy Summary](https://docs.apigee.com/static/api-platform/images/tutorial-build-proxy-summary.png)
16. Click **Mock-Target-API** to display the Overview page for the API proxy.  
    ![Summary of Mock Target API proxy](https://docs.apigee.com/static/api-platform/images/tutorial-mock-target-overview-v5.png)

Congratulations! You've created an API proxy from an OpenAPI Specification. Next you'll
test it to see how it works.

## Test the API proxy

You can test your `Mock-Target-API` API using cURL or a web browser.

In a terminal window, run the following cURL command. Substitute your organization name in
the URL.

> [!IMPORTANT]
> **Tip:** You can also enter the URL in a web browser to get the same response.

```
curl http://<org_name>-test.apigee.net/mock-target-api
```

**Response**

You should see the following response:

```
Hello, Guest!        
```

Way to go! You've built a simple API proxy from an OpenAPI Specification and tested
it.

## Add an XML to JSON policy

Next, you'll add the XML to JSON policy to the **View 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.
Substitute your organization name in the URL.

```
curl http://<org_name>-test.apigee.net/mock-target-api/xml
```

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

1. Click the **Develop** tab in the top right corner of the Mock-Target-API Overview page in the Edge UI.  
   ![Developer tab](https://docs.apigee.com/static/api-platform/images/tutorial-developtab.png)
2. In the left Navigator pane, under Proxy Endpoints \> default, click the **View
   XML Response** conditional flow.  
   ![Select View XML Response](https://docs.apigee.com/static/api-platform/images/tutorial-select-viewxml.png)
3. Click the bottom **+Step** button, corresponding to the **Response** for the flow.   
   ![Select +Step](https://docs.apigee.com/static/api-platform/images/tutorial-select-responsestep.png)  
   The Add Step dialog opens to display a categorized list of all the policies that you can add.  
4. Scroll to the Mediation category and select **XML to JSON** .  
   ![Add Step dialog](https://docs.apigee.com/static/api-platform/images/tutorial-add-step.png)
5. Keep the default values for **Display Name** and **Name**.
6. Click **Add** . The XML to JSON policy is applied to the response.![XML to JSON policy in flow](https://docs.apigee.com/static/api-platform/images/tutorial-xmltojson.png)
7. Click **Save**.

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 http://<org_name>-test.apigee.net/mock-target-api/xml
```

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.