diff --git a/en/docs/develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md b/en/docs/develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md new file mode 100644 index 0000000000..1e545d3516 --- /dev/null +++ b/en/docs/develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md @@ -0,0 +1,162 @@ +# Develop an API Proxy from a GitHub Repository Source + +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. + +In this guide, you will: + +- Create an API proxy component to expose an existing API. +- Deploy the API proxy. +- Test the API proxy to verify its functionality. +- Manage the API. +- Consume the API. + +## Prerequisites + +1. If you're signing in to the Choreo Console for the first time, create an organization: + 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in using your preferred method. + 2. Enter a unique organization name. For example, `Stark Industries`. + 3. Read and accept the privacy policy and terms of use. + 4. Click **Create**. + + This creates the organization and opens the **Project Home** page of the default project created for you. + +2. Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample proxy source](https://github.com/wso2/choreo-samples/tree/main/department-api-proxy-from-github). + +## Step 1: Create an API proxy + +You can create an API proxy either by selecting the source from a GitHub repository, uploading an OpenAPI specification file, or providing an OpenAPI specification URL. This guide demonstrates how to create an API proxy using a GitHub repository as the source. + +1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. +2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. +3. Click the **API Proxy** card. This opens the **Create an API Proxy** pane. + +4. Click on **Authorize With GitHub** card under **Connect a Git Repository** section 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). + + !!! note + The **Choreo GitHub App** requires the following permissions: + - Read and write access to code and pull requests. + - Read access to issues and metadata. + + 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. + +5. Enter the following repository details: + + | **Field** | **Value** | + |------------------------|--------------------| + | **Organization** | Your GitHub account| + | **Repository** | choreo-samples | + | **Branch** | **`main`** | + | **API Directory** | /department-api-proxy-from-github | + + !!! note + To select the relevant directory, click on the **Edit** action next to the **API Directory** input field. Then, enter `department-api-proxy-from-github` as the directory name to quickly search and locate the correct directory. + +6. Specify the following values as Proxy Metadata: + + !!! info + 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. + + | **Field** | **Value** | + |-----------------|--------------------------------------------| + | **Context** | `department-service` | + | **Version** | `v1.0` | + | **Target** | `https://samples.choreoapps.dev/company/hr`| + +7. Specify the following values as Component Details: + + !!! info + The **Component Name** field must be unique and cannot be changed after creation. This value is automatically generated, but you can edit it if necessary. + **Component Display Name** is a required field. + + | **Field** | **Value** | + |-----------------|--------------------------------------------| + | **Component Display Name**| `Department Service` | + | **Component Name** | `department-service` | + | **Description** | `This is a sample proxy for department service` | + +8. Click **Create**. This creates the API proxy component and takes you to the **Build** page. + +!!! note + When you create an API proxy from a GitHub repository source, the GitHub source serves as the single source of truth. Therefore, any modifications, such as adding or deleting resources, must be made through the GitHub repository. + +## Step 2: Build + +!!! info + The initial build starts automatically when you create the API proxy, and you will be redirected to the **Build** page. In this case, you can skip the steps below. If you need to manually trigger a build later, follow these steps. + +1. On the project home page, click on the `Department Service` component you created. This takes you to the component overview page. +2. In the left navigation menu, click **Build**. +3. On the **Build** page, click **Build Latest**. + +!!! note + The build process may take some time. You can track progress in the **Build Details** pane. Once complete, the build status changes to **Success**. + +## Step 3: Deploy the API proxy + +1. In the left navigation menu, click **Deploy**. +2. In the **Build Area** card, click **Configure & Deploy**. This opens the **Configure & Deploy** pane. +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. + +Now you are ready to test the API proxy. + +## Step 4: Test the API proxy + +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. + +!!! tip + Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. + + - 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. + - To disable security for the entire API or a specific resource: + 1. In the left navigation menu, click **Deploy**. + 2. Go to the **Build Area** card and click **Security Settings**. + 3. In the **Security Settings** pane: + - To disable security for the entire API, clear the **OAuth2** checkbox. + - To disable security for a specific resource, expand the relevant resource and turn off the **Security** toggle. + 4. Click **Apply**. + +1. In the left navigation menu, click **Test** and then click **OpenAPI Console**. +2. Select **Development** from the environment drop-down list. +3. Expand the `GET /department/{departmentId}` resource and click **Try it Out**. +4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![API proxy response](../../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} + + This indicates that your API proxy is working as expected. + +## Step 5: Manage the API proxy + +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. + +### Step 5.1: Apply rate limiting to the API proxy + +1. In the left navigation menu, click **Deploy**. +2. Go to the required environment card and click the settings icon corresponding to **API Configuration**. +3. In the **CORS, Rate Limiting and Resiliency** pane, click **Rate Limiting** to expand the section. +4. Select **API Level** as the **Rate Limiting Level**. +5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. You can proceed with the default values. +6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. + +### Step 5.2: Publish the API proxy + +1. In the left navigation menu, click **Lifecycle** under **Manage**. This takes you to the **Lifecycle** page. +2. Click **Publish**. +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**. + +## Step 6: Invoke the API + +To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps: + +1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `Department Service` in the Choreo Developer Portal. + +2. **Invoke the API**: + 1. In the Developer Portal left navigation menu, click **Try Out**. + 2. In the **Endpoint** list, select **Development** as the environment to try out the API. + 3. Click **Get Test Key** to generate an access token. + 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. + 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: + + ![Try out response](../../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} + +Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo. diff --git a/en/docs/develop-components/develop-an-api-proxy.md b/en/docs/develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md similarity index 74% rename from en/docs/develop-components/develop-an-api-proxy.md rename to en/docs/develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md index ca89f6cd30..7b59b50f84 100644 --- a/en/docs/develop-components/develop-an-api-proxy.md +++ b/en/docs/develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md @@ -1,4 +1,4 @@ -# Develop an API Proxy +# Develop an API Proxy from Scratch 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. @@ -27,22 +27,27 @@ To create an API proxy, you can either upload an OpenAPI specification or provid 1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page. 2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step. 3. Click the **API Proxy** card. This opens the **Create an API Proxy** pane. -4. Click **Skip Source** to define resources manually. -5. Specify the following values as API proxy details: - - !!! info - The **Name** field must be unique and cannot be changed after creation. +4. Select **Creare from Scratch** option. +5. Specify the following values as Proxy Metadata: | **Field** | **Value** | |-----------------|--------------------------------------------| - | **Display Name**| `HR API` | - | **Name** | `hr-api` | - | **Context** | `abc-hr` | + | **Context** | `department-service` | | **Version** | `1.0` | - | **Target** | `https://samples.choreoapps.dev/company/hr`| - | **Access Mode** | **External** | + | **Target** | `https://samples.choreoapps.dev/company/hr` | + +6. Enter following details for the Component Details: + + !!! info + The **Component Name** field must be unique and cannot be changed after creation. -6. Click **Create**. This creates the API proxy component and takes you to the **Overview** page. + | **Field** | **Value** | + |---------------------------|--------------------| + | **Component Display Name**| `Department Service` | + | **Component Name** | `department-service` | + | **Description** | `Sample proxy for department service` | + +7. Click **Create**. This creates the API proxy component and takes you to the **Deploy** page. ## Step 2: Define resources for the API proxy @@ -71,7 +76,7 @@ Now you are ready to test the API proxy. ## Step 4: Test the API proxy -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. +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. !!! tip Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API. @@ -90,7 +95,7 @@ Choreo allows you to test your API proxy using either the [integrated OpenAPI Co 3. Expand the `GET /department/{departmentId}` resource and click **Try it Out**. 4. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: - ![API proxy response](../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} + ![API proxy response](../../assets/img/develop-components/develop-a-rest-api-proxy/rest-api-proxy-response.png){.cInlineImage-full} This indicates that your API proxy is working as expected. @@ -101,8 +106,8 @@ Now that you have a tested API proxy, you can publish it and make it available f ### Step 5.1: Apply rate limiting to the API proxy 1. In the left navigation menu, click **Deploy**. -2. Go to the required environment card and click the settings icon corresponding to **API Configuration**. -3. In the **API Configuration** pane, click **Rate Limiting** to expand the section. +2. Go to the required environment card and click the settings icon corresponding to **CORS, Rate Limiting and Resiliency**. +3. In the **CORS, Rate Limiting and Resiliency** pane, click **Rate Limiting** to expand the section. 4. Select **API Level** as the **Rate Limiting Level**. 5. Specify appropriate values for the **Request Limit** and **Time Unit** fields. You can proceed with the default values. 6. Click **Apply**. This applies the rate limiting level to the API proxy and redeploys it. @@ -117,24 +122,15 @@ Now that you have a tested API proxy, you can publish it and make it available f To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps: -1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `HR API` in the Choreo Developer Portal. - -2. **Generate Credentials**: - 1. In the Developer Portal left navigation menu, click **Production** under **Credentials**. - 2. Click **Generate Credentials**. Choreo generates new tokens and populates the **Consumer Key** and **Consumer Secret** fields. +1. In the **Lifecycle** page, click **Go to Devportal**. This takes you to the `Department Service` in the Choreo Developer Portal. - !!! tip - 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. - -3. **Invoke the API**: +2. **Invoke the API**: 1. In the Developer Portal left navigation menu, click **Try Out**. 2. In the **Endpoint** list, select **Development** as the environment to try out the API. 3. Click **Get Test Key** to generate an access token. 4. Expand the `GET /department/{departmentId}` resource and click **Try it out**. 5. Enter `1` as the **departmentId** and click **Execute**. You will see a response similar to the following: - ![Try out response](../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} - -Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo API Manager. + ![Try out response](../../assets/img/develop-components/develop-a-rest-api-proxy/try-out-response.png){.cInlineImage-full} -To learn more about the API management capabilities supported by Choreo API Manager, see [API Management](../api-management/lifecycle-management.md). +Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo. \ No newline at end of file diff --git a/en/mkdocs.yml b/en/mkdocs.yml index f0760349db..dc824af5fc 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -103,7 +103,7 @@ nav: - Develop Services: - Service Component Overview: develop-components/develop-services/service-component-overview.md - Develop a Service: develop-components/develop-services/develop-a-service.md - - Develop a service with Docker: develop-components/develop-services/develop-a-service-with-docker.md + - Develop a Service with Docker: develop-components/develop-services/develop-a-service-with-docker.md - Develop a Ballerina Service: develop-components/develop-services/develop-a-ballerina-service.md - Expose a gRPC Endpoint via a Service: develop-components/develop-services/expose-a-grpc-endpoint-via-a-service.md - Expose a TCP Server via a Service: develop-components/develop-services/expose-a-tcp-server-via-a-service.md @@ -111,7 +111,9 @@ nav: - Expose a Ballerina GraphQL Endpoint via a Service: develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md - Expose a Prism-Based Mock Server Using an OpenAPI Specification: develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md - Expose a WebSocket Endpoint via a Service: develop-components/develop-services/expose-a-websocket-endpoint-via-a-service.md - - Develop an API Proxy: develop-components/develop-an-api-proxy.md + - Develop an API Proxy: + - Develop an API Proxy from Scratch : develop-components/develop-proxy/develop-an-api-proxy-from-scratch.md + - Develop an API Proxy from Git Repository Source : develop-components/develop-proxy/develop-an-api-proxy-from-a-github-repository-source.md - Develop Web Applications: - Build and Deploy a Single-Page Web Application: develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md - Develop Web Applications Locally with Choreo’s Managed Authentication: develop-components/develop-web-applications/develop-web-applications-locally-with-managed-authentication.md @@ -396,7 +398,7 @@ plugins: 'testing/test-apis-with-choreo-testgpt.md': 'https://wso2.com/choreo/docs/testing/test-apis-with-choreo-apichat/' 'develop-integrations/develop-an-event-triggered-integration.md': 'https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-an-event-handler/' 'develop-integrations/develop-a-scheduled-integration.md': 'https://wso2.com/choreo/docs/develop-components/develop-integrations/develop-a-scheduled-task/' - 'develop-components/develop-a-rest-api-proxy.md': 'https://wso2.com/choreo/docs/develop-components/develop-an-api-proxy/' + 'develop-components/develop-a-rest-api-proxy.md': 'https://wso2.com/choreo/docs/develop-components/develop-proxy/' 'devops-and-ci-cd/builds-and-deployments.md' : 'https://wso2.com/choreo/docs/choreo-concepts/ci-cd/' 'troubleshoot/faq.md': 'https://wso2.com/choreo/docs/references/faq/' 'develop-components/develop-services/develop-a-rest-api.md': 'https://wso2.com/choreo/docs/develop-components/develop-services/develop-a-service/' diff --git a/en/theme/material/templates/home-page-2.html b/en/theme/material/templates/home-page-2.html index 305350007d..65cfe68b35 100644 --- a/en/theme/material/templates/home-page-2.html +++ b/en/theme/material/templates/home-page-2.html @@ -405,7 +405,7 @@

- Develop an API Proxy + Develop an API Proxy