Skip to content

Developer-Driven Design First API Management

This section provides a step-by-step guide to creating, deploying, and invoking an API using the WSO2 Kubernetes Gateway integrated with the Control Plane. It also covers how to create an API from the data plane using CR and APIs.

Note

To set up the Kubernetes Gateway as an enterprise version, please follow the steps specified in both the Install WSO2 Kubernetes Gateway Enterprise and Install WSO2 Kubernetes Gateway Agent Enterprise.

Note

If you follow this approach, you cannot create APIs from Portal UI. If you need that approach, go to Portal-Driven Design First section.

Before you begin...

Install the prerequisites that are required to run the WSO2 Kubernetes Gateway.

Note

If you already have an installation of the Kubernetes gateway in your cluster, please remove the installation by following the steps specified in the Uninstall Kubernetes Gateway section.

Step 1 - Setup WSO2 Kubernetes Gateway With Control Plane

Follow the instructions below to deploy Kubernetes Gateway in the Kubernetes cluster.

Create Kubernetes namespace

kubectl create ns apk

Set up WSO2 API Manager Control Plane 4.5.0

Set up WSO2 API Manager 4.5.0 in a Kubernetes cluster using Helm charts.

  1. Create a new Helm repository with the latest APIM release using the following command. Let's consider the <repository-name> as wso2apim.

    console helm repo add wso2apim https://github.com/wso2/helm-apim/releases/download/acp-4.5.0

  2. Execute the following command to update the Helm repositories.

    console helm repo update

  3. Install the API Manager Control Plane.

    Consider apim as the <chart-name> for this guide. For the --version parameter, use the version corresponding to the release from step 1. The deployment will take a few minutes to complete.

    helm install apim wso2apim/wso2am-acp --version 4.5.0-1 -f https://raw.githubusercontent.com/wso2/apk/main/helm-charts/samples/apim/cp/apk-cp/4.5.0-values.yaml -n apk

    helm install <chart-name> <repository-name>/wso2am-acp --version <version-of-APIM> -f <path-to-values.yaml-file>

  4. Install the NGINX Ingress Controller.

    Please refer to the NGINX Ingress Controller documentation for more information.

Set up WSO2 Kubernetes Gateway 1.3.0

  1. Create a new Helm repository with the latest Kubernetes Gateway release using the following command. Let's consider the <repository-name> as wso2apk.

    console helm repo add wso2apk https://github.com/wso2/apk/releases/download/1.3.0-1

  2. Execute the following command to update the Helm repositories.

    console helm repo update

  3. Install the Kubernetes Gateway components and start WSO2 API Platform For Kubernetes.

    Consider apk as the <chart-name> for this guide. For the --version parameter, use the version corresponding to the release from step 1. The deployment will take a few minutes to complete.

    helm install apk wso2apk/apk-helm --version 1.3.0 -f https://raw.githubusercontent.com/wso2/apk/main/helm-charts/samples/apk/1.3.0-values.yaml -n apk

    helm install <chart-name> <repository-name>/apk-helm --version <version-of-APK> -f <path-to-values.yaml-file>

Set up WSO2 Kubernetes Gateway Agent 1.3.0

  1. Create a new Helm repository with the latest Kubernetes Gateway Agent release using the following command. Let's consider the <repository-name> as wso2apkagent for this guide.

    console helm repo add wso2apkagent https://github.com/wso2/product-apim-tooling/releases/download/1.3.0

  2. Execute the following command to update the Helm repositories.

    console helm repo update

  3. Install the Kubernetes Gateway Agent components and start WSO2 Kubernetes Gateway.

    Consider apk as the <chart-name> for this guide. For the --version parameter, use the version corresponding to the release from step 1. The deployment will take a few minutes to complete.

    helm install apim-apk-agent wso2apkagent/apim-apk-agent --version 1.3.0 -f https://raw.githubusercontent.com/wso2/apk/main/helm-charts/samples/apim-apk-agent/cp/1.3.0-values.yaml -n apk

    helm install <chart-name> <repository-name>/apim-apk-agent --version <version-of-APK-Agent> -f <path-to-values.yaml-file>

Verify the Deployment

You can verify the deployment by executing the following command. Once completed, you will see the status of the pods for Kubernetes Gateway and APIM Control Plane as shown below.

kubectl get pods -n apk Pod Status

Step 2 - Create and Deploy the API From Dataplane

  1. Download and save the sample SampleAPIDefinition.json file. This is the OAS definition of the API that we are going to deploy in Kubernetes Gateway.

  2. Add a hostname mapping to the /etc/hosts file as follows.

    IP Domain name
    127.0.0.1 api.am.wso2.com
    127.0.0.1 am.wso2.com
    127.0.0.1 idp.am.wso2.com
    127.0.0.1 default.gw.wso2.com
    127.0.0.1 carbon.super.gw.wso2.com

(Optional) To access the deployment through your local machine

  1. Identify the gateway-service external IP address. console kubectl get svc -n apk | grep gateway-service
  2. Port forward router service to localhost. console kubectl port-forward svc/apk-wso2-apk-gateway-service 9095:9095 -n apk

Generate Kubernetes Gateway configuration file from the OpenAPI definition

Apart from the above API definition file, we also need an apk-conf file that defines the configurations and metadata for this API. We have a configuration service that can be used to generate this apk-conf file when the OpenAPI definition is provided.

  1. Execute the following request to generate the Kubernetes Gateway API configuration. Use the values provided in the table below in the body of your request.

    Field Value
    definition SampleAPIDefinition.json file that was downloaded at the beginning of Step 2

    curl -k --location 'https://api.am.wso2.com:9095/api/configurator/1.3.0/apis/generate-configuration' \ --header 'Host: api.am.wso2.com' \ --form 'definition=@"/Users/user/SampleAPIDefinition.json"' > SampleService.apk-conf

    ```

    name: "Sample API" basePath: "/U2FtcGxlIEFQSTAuMS4w" version: "0.1.0" type: "REST" defaultVersion: false subscriptionValidation: false endpointConfigurations: production: - endpoint: "https://dev-tools.wso2.com/gs/helpers/v1.0" operations: - target: "/ai/spelling" verb: "POST" secured: true scopes: [] - target: "/base64/decode/{value}" verb: "POST" secured: true scopes: [] - target: "/base64/encode/{value}" verb: "POST" secured: true scopes: [] - target: "/ip" verb: "GET" secured: true scopes: [] - target: "/user-agent" verb: "GET" secured: true scopes: [] - target: "/uuid" verb: "GET" secured: true scopes: [] ```

    curl --location 'https://<host>:9095/api/configurator/1.3.0/apis/generate-configuration' \ --header 'Host: <host>' \ --form 'apiType="<api-type>"' \ --form 'definition=@"<path/to/SampleAPIDefinition.json>"'

  2. You will get the apk-conf file content as the response. Save this content into a file named SampleService.apk-conf. You can edit these values as necessary. Let's change the basepath from the autogenerated value to "/sample-api". Your apk-conf file should now appear as follows.

```

name: "Sample API" basePath: "/sample-api" version: "0.1.0" type: "REST" defaultVersion: false subscriptionValidation: false endpointConfigurations: production: - endpoint: "https://dev-tools.wso2.com/gs/helpers/v1.0" operations: - target: "/ai/spelling" verb: "POST" secured: true scopes: [] - target: "/base64/decode/{value}" verb: "POST" secured: true scopes: [] - target: "/base64/encode/{value}" verb: "POST" secured: true scopes: [] - target: "/ip" verb: "GET" secured: true scopes: [] - target: "/user-agent" verb: "GET" secured: true scopes: [] - target: "/uuid" verb: "GET" secured: true scopes: [] ```

Important

We recommend installing the Kubernetes Gateway Config Language Support Visual Studio Code (VS Code) extension to edit the Kubernetes Gateway API Configuration file.

Deploy the API in Kubernetes Gateway

You now have the API Definition (SampleAPIDefinition.json) and the apk-conf file (SampleService.apk-conf) corresponding to the API. We can use these files to deploy the API in Kubernetes Gateway.

  1. Use the values provided in the table below in the body of your request.

    Field Value Required
    apkConfiguration SampleService.apk-conf file
    definitionFile SampleAPIDefinition.json file

  2. You can generate the Kubernetes custom resources as a zip file from the config-deployer service using the following command.

    curl --location 'https://api.am.wso2.com:9095/api/configurator/1.3.0/apis/generate-k8s-resources?organization=carbon.super' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/zip' \ --form 'apkConfiguration=@"/Users/user/SampleService.apk-conf"' \ --form 'definitionFile=@"/Users/user/SampleAPIDefinition.json"' \ -k --output ./api-crds.zip

    curl --location 'https://<host>:9095/api/configurator/1.3.0/apis/generate-k8s-resources?organization=carbon.super' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/zip' \ --form 'apkConfiguration=@"<path/to/apk-conf-file.apk-conf>"' \ --form 'definitionFile=@"<path/to/definition-file.json>"' \ -k --output <path/and/name-for-generated-zip-file.zip>

  3. Once you have generated your K8s artifacts, the next step is to apply them to the Kubernetes API server.

    kubectl apply -n apk -f <path_to_extracted_zip_file>

  4. Execute the command below. You will be able to see that the SampleServiceAPI is successfully deployed as shown in the image.

    kubectl get apis -n apk

    Deployed API

Step 3 - Manage API From Control Plane

  1. Login to the Publisher Console (https://am.wso2.com/publisher) of the WSO2 API Manager.

    you can see the deployed SampleService API as below.

    ControlPlane API

  2. Once you click the API you will be redirected to the overview page.

    ControlPlaneOverview API

  3. Now you can edit portal configurations such as basic info, documentation etc.

    ControlPlaneBasic API

  4. Finally publish to developer portal.

Step 4 - Create Application and Subscribe to the API

  1. Login to the Developer Portal (https://am.wso2.com/devportal) of the WSO2 API Manager.
  2. Click on the Applications tab and then use ADD NEW APPLICATION option.

  3. Provide the information as given below and click Save.

    FieldValue
    Application NameSampleServiceApp
    Per Token Quota10PerMin
    DescriptionSample Service Application

  4. Click Subscriptions to subscribe to the created SampleServiceAPI.

  5. Click Production Keys or Sandbox Keys based on the environment for which you need to generate keys. Let's assume that you are working in a production environment. Therefore, click Production Keys.
  6. Click Generate Keys to create an application Access Token with relevant scopes.

  7. To verify the Application and Subscription creation in the kubernetes gateway, execute the following command. You will see the status of the deployed application as follows once completed.

    bash kubectl get subscriptions -n apk kubectl get applications -n apk

Step 5 - Invoke the API

  1. Generate an access token by following the steps under Generate an access token to invoke APIs section.

  2. Use the following command to invoke the API using the access token generated in the previous step.

    bash curl -X GET "https://carbon.super.gw.wso2.com:9095/sample-api/0.1.0/uuid" -H "Authorization: Bearer <access-token>" -k

You will now be able to see a successful response with the details of a random UUID from the sample backend that we used for this guide.