|
| 1 | +# Develop an API Proxy from a GH source |
| 2 | + |
| 3 | +An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. |
| 4 | + |
| 5 | +In this guide, you will: |
| 6 | + |
| 7 | +- Create an API proxy component to expose an existing API. |
| 8 | +- Deploy the API proxy. |
| 9 | +- Test the API proxy to verify its functionality. |
| 10 | +- Manage the API. |
| 11 | +- Consume the API. |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +- If you're signing in to the Choreo Console for the first time, create an organization: |
| 16 | + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. |
| 17 | + 2. Enter a unique organization name. For example, `Stark Industries`. |
| 18 | + 3. Read and accept the privacy policy and terms of use. |
| 19 | + 4. Click **Create**. |
| 20 | + |
| 21 | + This creates the organization and opens the **Project Home** page of the default project created for you. |
| 22 | + |
| 23 | +## Step 1: Create an API proxy |
| 24 | + |
| 25 | +To create an API proxy, you can either choose from a github repository, upload an OpenAPI specification or provide an OpenAPI specification URL. In this guide, you will specify a URL to an OpenAPI definition of a sample API. |
| 26 | + |
| 27 | +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. |
| 28 | +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. |
| 29 | +3. Click the **API Proxy** card. This opens the **Create an API Proxy** pane. |
| 30 | +4. You will see the three options to create a proxy component and here we select github option (selected by default). |
| 31 | +5. Specify the following values as component details: |
| 32 | + |
| 33 | + !!! info |
| 34 | + The **Component Name** field must be unique and cannot be changed after creation.System will generate a unique name for you. But you are free to change the generated name. |
| 35 | + **Component Display Name** is a required field. |
| 36 | + |
| 37 | + | **Field** | **Value** | |
| 38 | + |-----------------|--------------------------------------------| |
| 39 | + | **Component Display Name**| `Pet Service` | |
| 40 | + | **Component Name** | `pet-service` | |
| 41 | + | **Description** | `This is a sample pet store` | |
| 42 | + |
| 43 | +6. Go to the **GitHub** tab. |
| 44 | + - Click **Authorize with GitHub** to connect your GitHub account. If you haven’t connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you forked in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps). |
| 45 | + |
| 46 | + !!! note |
| 47 | + The **Choreo GitHub App** requires the following permissions: |
| 48 | + - Read and write access to code and pull requests. |
| 49 | + - Read access to issues and metadata. |
| 50 | + |
| 51 | + You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if needed. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository. |
| 52 | + |
| 53 | +6. Enter the following repository details: |
| 54 | + |
| 55 | + | **Field** | **Value** | |
| 56 | + |------------------------|--------------------| |
| 57 | + | **Organization** | Your GitHub account| |
| 58 | + | **Repository** | choreo-samples | |
| 59 | + | **Branch** | **`main`** | |
| 60 | + | **API Directory** | /choreo-samples/proxy-from-gh/pet-service | |
| 61 | + |
| 62 | +7. Specify the following values as API proxy details: |
| 63 | + |
| 64 | + !!! info |
| 65 | + The **Context** field must be unique and cannot be changed after creation.**Version** and **Target** are mandatory fields. **Target** can be changed at any time after the creation. |
| 66 | + |
| 67 | + | **Field** | **Value** | |
| 68 | + |-----------------|--------------------------------------------| |
| 69 | + | **Context** | `pet/v1` | |
| 70 | + | **Version** | `V1.0` | |
| 71 | + | **Target** | `https://samples.choreoapps.dev/company/pet-service`| |
| 72 | + |
| 73 | +6. Click **Create**. This creates the API proxy component and takes you to the **Overview** page. |
| 74 | + |
| 75 | +## Step 2: Define resources for the API proxy |
| 76 | + |
| 77 | +!!! note |
| 78 | + When you creating an API proxy by **pointing a github repository** , the GH source consider as the **single source of truth**. So , the only way is to change API resources like resource addition, deletion of modifications should be done trought the GH source. |
| 79 | + |
| 80 | +## Step 3: Deploy the API proxy |
| 81 | + |
| 82 | +1. In the left navigation menu, click **Deploy**. |
| 83 | +2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane. |
| 84 | +3. Select **External** as the API access mode and click **Deploy**. The **Development** card indicates the **Deployment Status** as **Active** when the API proxy is successfully deployed. |
| 85 | + |
| 86 | +Now you are ready to test the API proxy. |
| 87 | + |
| 88 | +## Step 4: Test the API proxy |
| 89 | + |
| 90 | +Choreo allows you to test your API proxy using either the [integrated OpenAPI Console](../../testing/test-rest-endpoints-via-the-openapi-console.md) or [cURL](../../testing/test-apis-with-curl.md). In this guide, you will use the OpenAPI Console. |
| 91 | + |
| 92 | +!!! tip |
| 93 | + Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. |
| 94 | + |
| 95 | + - Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the **Security Header** field. |
| 96 | + - To disable security for the entire API or a specific resource: |
| 97 | + 1. In the left navigation menu, click **Deploy**. |
| 98 | + 2. Go to the **Build Area** card and click **Security Settings**. |
| 99 | + 3. In the **Security Settings** pane: |
| 100 | + - To disable security for the entire API, clear the **OAuth2** checkbox. |
| 101 | + - To disable security for a specific resource, expand the relevant resource and turn off the **Security** toggle. |
| 102 | + 4. Click **Apply**. |
| 103 | + |
| 104 | +1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. |
| 105 | +2. Select **Development** from the environment drop-down list. |
| 106 | +3. Expand the `GET /department/{departmentId}` resource and click **Try it Out**. |
| 107 | +4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: |
| 108 | + |
| 109 | + {.cInlineImage-full} |
| 110 | + |
| 111 | + This indicates that your API proxy is working as expected. |
| 112 | + |
| 113 | +## Step 5: Manage the API proxy |
| 114 | + |
| 115 | +Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. In this guide, you will apply rate limiting to the API and publish it. |
| 116 | + |
| 117 | +### Step 5.1: Apply rate limiting to the API proxy |
| 118 | + |
| 119 | +1. In the left navigation menu, click **Deploy**. |
| 120 | +2. Go to the required environment card and click the settings icon corresponding to **API Configuration**. |
| 121 | +3. In the **API Configuration** pane, click **Rate Limiting** to expand the section. |
| 122 | +4. Select **API Level** as the **Rate Limiting Level**. |
| 123 | +5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. You can proceed with the default values. |
| 124 | +6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. |
| 125 | + |
| 126 | +### Step 5.2: Publish the API proxy |
| 127 | + |
| 128 | +1. In the left navigation menu, click **Lifecycle** under **Manage**. This takes you to the **Lifecycle** page. |
| 129 | +2. Click **Publish**. |
| 130 | +3. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the API lifecycle state to **Published**. |
| 131 | + |
| 132 | +## Step 6: Invoke the API |
| 133 | + |
| 134 | +To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps: |
| 135 | + |
| 136 | +1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `HR API` in the Choreo Developer Portal. |
| 137 | + |
| 138 | +2. **Generate Credentials**: |
| 139 | + 1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. |
| 140 | + 2. Click **Generate Credentials**. Choreo generates new tokens and populates the **Consumer Key** and **Consumer Secret** fields. |
| 141 | + |
| 142 | + !!! tip |
| 143 | + To test the API via an API test tool or through code, click **Generate Access Token** and copy the test token. Alternatively, click **cURL** and copy the generated cURL command to use via a cURL client. You do not need to generate an access token if you are testing the API via the **Try Out** capability in the Choreo Developer Portal. |
| 144 | + |
| 145 | +3. **Invoke the API**: |
| 146 | + 1. In the Developer Portal left navigation menu, click **Try Out**. |
| 147 | + 2. In the **Endpoint** list, select **Development** as the environment to try out the API. |
| 148 | + 3. Click **Get Test Key** to generate an access token. |
| 149 | + 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. |
| 150 | + 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: |
| 151 | + |
| 152 | + {.cInlineImage-full} |
| 153 | + |
| 154 | +Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo API Manager. |
| 155 | + |
| 156 | +To learn more about the API management capabilities supported by Choreo API Manager, see [API Management](../../api-management/lifecycle-management.md). |
0 commit comments