Quick Start Guide

This section is a step-by-step guide to creating, deploying, and invoking an API using the WSO2 API Platform For Kubernetes.

Note

To set up the APK as an enterprise version, please follow the steps specified in the Install APK Enterprise section.

Before you begin...

Install the prerequisites that are required to run the WSO2 API Platform For Kubernetes.

Note

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

Step 1 - Start WSO2 API Platform For Kubernetes

Follow the instructions below to deploy APK Data Service (DS) servers and the Cloud Native Postgres(CloudNativePG) in the Kubernetes cluster.

Install APK

1. Create a new helm repository with the latest apk release using the following command. Let’s consider the <repository-name> as wso2apk for this guide.

   helm repo add wso2apk https://github.com/wso2/apk/releases/download/1.1.0
   

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

   helm repo update
   

3. Install the APK components and start WSO2 API Platform For Kubernetes. Consider apk as the <chart-name> for this guide. As the --version of this command, use the version of the release you used in point 1 above. It will take a few minutes for the deployment to complete.

CommandFormat

helm install apk wso2apk/apk-helm --version 1.1.0

helm install <chart-name> <repository-name>/apk-helm --version <version-of-APK>

Optional

To commence the installation while making use of the customization capabilities inherent in the values.yaml file, follow the subsequent command format. Instructions in Customize Configurations will guide you through the process of acquiring the values.yaml file.

CommandFormat

helm install apk wso2apk/apk-helm --version 1.1.0 -f values.yaml

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

If you want to update the values of an existing APK installation, please execute the following helm upgrade command. Use the --no-hooks flag to disable the hooks available in the APK helm chart.

CommandFormat

helm upgrade apk wso2apk/apk-helm --version 1.1.0 -f values.yaml --no-hooks

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

Verify the deployment

Now you can verify the deployment by executing the following command. You will see the status of the pods as follows once completed.

Command

kubectl get pods

Important

If pods are not transitioning to running state, please follow the steps in the FAQs to troubleshoot the problem.

Step 2 - Create the Backend

For this guide, we will be using a backend deployed in a Kubernetes service. Prior to invoking the API, you will need to have this backend up.

You can create the sample backend with the following command.

kubectl apply -f https://raw.githubusercontent.com/wso2/apk/main/developer/tryout/samples/qsg-sample-backend.yaml

Wait for this pod to spin up. You can check its status using the following command.

kubectl get pods

Step 3 - Create and Deploy the API

1. Save and download the sample EmployeeServiceDefinition.json file. This is the OAS definition of the API that we are going to deploy in APK.

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	idp.am.wso2.com
   127.0.0.1	default.gw.wso2.com

(Optional) To access the deployment through your local machine

1. Identify the gateway-service external IP address.

   kubectl get svc | grep gateway-service
   

2. Port forward router service to localhost.

   kubectl port-forward svc/apk-wso2-apk-gateway-service 9095:9095
   

Generate APK 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 APK configuration. Use the values provided in the table below in the body of your request.

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

   Sample RequestSample ResponseRequest Format

   curl -k --location 'https://api.am.wso2.com:9095/api/configurator/1.1.0/apis/generate-configuration' \
   --header 'Host: api.am.wso2.com' \
   --form 'definition=@"/Users/user/EmployeeServiceDefinition.json"'
   

   ---
   name: "EmployeeServiceAPI"
   basePath: "/RW1wbG95ZWVTZXJ2aWNlQVBJMy4xNA"
   version: "3.14"
   type: "REST"
   defaultVersion: false
   endpointConfigurations:
       production:
           endpoint: "http://employee-service:80"
   operations:
   - target: "/employee"
       verb: "GET"
       secured: true
       scopes: []
   - target: "/employee"
       verb: "POST"
       secured: true
       scopes: []
   - target: "/employee/{employeeId}"
       verb: "PUT"
       secured: true
       scopes: []
   - target: "/employee/{employeeId}"
       verb: "DELETE"
       secured: true
       scopes: []
   

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

2. You will get the apk-conf file content as the response. Save this content into a file named EmployeeService.apk-conf.

Important

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

Generate an access token to invoke APIs

To invoke the system APIs such as for deploying, we need a valid access token issued by an identity provider (IdP). While APK supports third-party IdPs such as Asgardeo and Auth0, it also supports an inbuilt non-production identity provider as well, which is only meant for testing purposes. We are going to use the non-production inbuilt IdP for this guide.

Note

If you are using a different organization to the one used in this guide, you will have to create a TokenIssuer with the relevant organization name in APK before proceeding to the next step. You can use the Add Token Issuer to create a new token issuer.

1. We will be using the client credentials grant type to generate the token.

   Sample RequestSample ResponseRequest Format

   curl -k --location 'https://idp.am.wso2.com:9095/oauth2/token' \
   --header 'Host: idp.am.wso2.com' \
   --header 'Authorization: Basic NDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyOjRmYmQ2MmVjLWE5MmUtMTFlZC1hZmExLTAyNDJhYzEyMDAwMg==' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials' \
   --data-urlencode 'scope=apk:api_create'
   

   {"access_token":"eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ", "token_type":"Bearer", "expires_in":3600, "scope":"default"}
   

   curl --location 'https://<host>:9095/oauth2/token' \
   --header 'Host: <host>' \
   --header 'Authorization: Basic <Base64Encoded(clientId:clientSecret)>' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials'
   

   Important

   These credentials and access tokens are from the inbuilt non-production sample application, and should only be used for testing purposes.

   Now you can use this access token to invoke the Resources and APIs that follow.

Deploy the API in APK

You now have the API Definition (EmployeeServiceDefinition.json) and the apk-conf file (EmployeeService.apk-conf) corresponding to the API. We can use these files to deploy the API in APK.

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

   Field	Value	Required
   apkConfiguration	EmployeeService.apk-conf file
   definitionFile	EmployeeServiceDefinition.json file

2. Set the access token in the Authorization header as a bearer token. This is the access token received by following the steps under the "Generate an access token to invoke APIs" section above.

3. Once the backend service you created is up and running, execute the API deployment request. You will receive a successful response with an autogenerated id for the API.

   Sample RequestSample ResponseRequest Format

   curl -k --location 'https://api.am.wso2.com:9095/api/deployer/1.1.0/apis/deploy' \
   --header 'Host: api.am.wso2.com' \
   --header 'Authorization: bearer eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ' \
   --form 'apkConfiguration=@"/Users/user/EmployeeService.apk-conf"' \
   --form 'definitionFile=@"/Users/user/EmployeeServiceDefinition.json"'
   

   ---
   id: "3940857a942e08686e58b511d43d046a7168281e"
   name: "EmployeeServiceAPI"
   basePath: "/RW1wbG95ZWVTZXJ2aWNlQVBJMy4xNA"
   version: "3.14"
   type: "REST"
   defaultVersion: false
   endpointConfigurations:
       production:
           endpoint: "http://employee-service:80"
   operations:
   - target: "/employee"
       verb: "GET"
       secured: true
       scopes: []
   - target: "/employee"
       verb: "POST"
       secured: true
       scopes: []
   - target: "/employee/{employeeId}"
       verb: "PUT"
       secured: true
       scopes: []
   - target: "/employee/{employeeId}"
       verb: "DELETE"
       secured: true
       scopes: []
   

   curl --location 'https://<host>:9095/api/deployer/1.1.0/apis/deploy' \
   --header 'Host: <host>' \
   --header 'Authorization: bearer <access-token>' \
   --form 'apkConfiguration=@"path/to/EmployeeService.apk-conf"' \
   --form 'definitionFile=@"path/to/EmployeeServiceDefinition.json"'
   

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

   Command

   kubectl get apis
   

   

Step 4 - Invoke the API

Now the API is ready to be invoked. Let’s get the list of Employees by invoking the /employee resource in the EmployeeServiceAPI.

1. Execute the following request to invoke the API. Make sure to provide the access token obtained in the previous step under "Generate an access token to invoke APIs" section as the Authorization header in this request.

   Sample RequestSample ResponseRequest Format

   curl -k --location 'https://default.gw.wso2.com:9095/RW1wbG95ZWVTZXJ2aWNlQVBJMy4xNA/3.14/employee' \
   --header 'Host: default.gw.wso2.com' \
   --header 'Authorization: bearer eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ'
   

   [
       {
           "id": "1234123",
           "name": "Mrs. Heily Feyers",
           "department": "IT"
       },
       {
           "id": "23451234",
           "name": "Mr. Brendon MacSmith",
           "department": "Sales"
       },
       {
           "id": "34561234",
           "name": "Mr. Peter Queenslander",
           "department": "IT"
       },
       {
           "id": "45671243",
           "name": "Miss. Liza MacAdams",
           "department": "Finance"
       }
   ]
   

   curl --location 'https://<host>:9095/<basePath>/3.14/employee' \
   --header 'Host: <host>' \
   --header 'Authorization: bearer <access-token>'
   

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

Note

To invoke the APIs, we need a valid access token issued by an identity provider (IdP). APK supports third-party IdPs such as Asgardeo and Auth0. Refer Configure IDP.

If you encounter any issues during the installation process, don't worry! We've compiled a list of frequently asked questions (FAQs) to help you troubleshoot common problems. Please refer to the FAQs section in this guide for step-by-step solutions to common installation issues.