Via REST API

Follow the instructions below to create a REST API using the APK config deployer REST API.

Step 1. Develop a backend service

To begin, it's essential to have a backend service that your API will interact with. The Kubernetes Gateway Configuration file is generated based on the API schema, which, in turn, relies on the functionality of your backend service.

This guide utilizes a pre-existing backend service hosted in the cloud. When using your own backend deployed in a Kubernetes cluster, ensure that backend is up and running prior to invoking the API.

Step 2. Generate an API schema file for your service.

You will need an OpenAPI Specification 3.x that describes the structure and behavior of your API. This file serves as the foundation for configuring your API and is essential for generating the Kubernetes Gateway Configuration file.

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.

Step 3. Generate Kubernetes Gateway configuration file.

This service generates a Kubernetes Gateway configuration file by providing your 3.x OpenAPI specification file. Kubernetes Gateway configuration file includes important API metadata, rate limiting details, security settings, and other necessary information about your API.

The OpenAPI specification file can be provided as a local file or as a URL containing a definition file.

1. As a local file

   bash curl -k --location 'https://api.example.com:9095/api/configurator/1.3.0/apis/generate-configuration' \ --header 'Host: api.example.com' \ --form 'definition=@"/Users/user/SampleAPIDefinition.json"'

2. As a URL

   The following URLs contain valid sample definitions that you can use.

   OpenAPI Specification for REST API:

   bash curl -k --location 'https://api.example.com:9095/api/configurator/1.3.0/apis/generate-configuration' \ --header 'Host: api.example.com' \ --form 'url="https://raw.githubusercontent.com/wso2/docs-apk/refs/heads/1.3.0/en/docs/assets/files/get-started/SampleAPIDefinition.json"' \ --form 'apiType="REST"'

   The sample output of the generated Kubernetes Gateway Configuration (apk-conf) file will be as follows.

   yaml name: "Sample API" basePath: "/sample-api" version: "0.1.0" type: "REST" defaultVersion: 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: []

Step 4. Save the response to a file with the extension .apk-conf.

For example, you can save under the name SampleService.apk-conf.

Step 5. Update the Kubernetes Gateway configuration file.

Review the content inside the apk-conf file and update it with additional API configurations as needed, such as rate limits, CORS configurations, etc.

Note

To optimize the configuration process, Kubernetes Gateway presents a VS Code plugin designed to offer syntax highlighting and intelligent suggestions. This plugin simplifies the incorporation of rate limitations, new resources, and security configurations into your API. Adapt the contents of the Kubernetes Gateway Configuration file as needed. For further details, refer to the section on Enhance Configuration with Kubernetes Gateway Config Language Support.

Step 6. Deploy the API to a Kubernetes cluster.

Once you have crafted your APK Configuration File, you have two convenient options for deploying them. Choose the deployment option that best suits your development workflow. Whether you prefer the customization capabilities of the Config Generator and CI/CD pipeline or the simplicity and speed of the Config Deployer, APK empowers you with flexible and efficient API deployment methods in the Kubernetes ecosystem.

Option 1 - Deploy API using APK Config Deployer tool

You can deploy the API directly into Kubernetes Gateway using API Schema definition and Kubernetes Gateway configuration file using the command below.

curl --location 'https://api.example.com:9095/api/deployer/1.3.0/apis/deploy' \ --header 'Content-Type: multipart/form-data' \ --header 'Accept: application/yaml' \ --header 'Authorization: Bearer <Access Token From IDP>' \ --form 'apkConfiguration=@"/Users/user/SampleService.apk-conf"' \ --form 'definitionFile=@"/Users/user/SampleAPIDefinition.json"'

Once we invoke the above API, the response body would look like below.

yaml id: "2d43a29159fbc77652b687243d545a7038c3abd6" name: "Sample API" basePath: "/sample-api" version: "0.1.0" type: "REST" defaultVersion: 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: []

Option 2 - Generate K8s CRs using config generator tool and Deploy the API using Kubernetes Client

You can generate K8s resources as a zip file from config-deployer service.

curl --location 'https://api.example.com:9095/api/configurator/1.3.0/apis/generate-k8s-resources' \ --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

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

kubectl apply -f <path_to_extracted_zip_file>

Step 7. Invoke the API.

Now the API is ready to be invoked. Let’s get a random UUID by invoking the /uuid resource in the SampleServiceAPI by invoking the API.

Sample RequestSample ResponseRequest Format

curl -k --location 'https://default.gw.example.com:9095/sample-api/0.1.0/uuid' \ --header 'Host: default.gw.example.com' \ --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QiLCAia2lkIjoiZ2F0ZXdheV9jZXJ0aWZpY2F0ZV9hbGlhcyJ9.eyJpc3MiOiJodHRwczovL2lkcC5hbS53c28yLmNvbS90b2tlbiIsICJzdWIiOiI0NWYxYzVjOC1hOTJlLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCAiZXhwIjoxNjg4MTMxNDQ0LCAibmJmIjoxNjg4MTI3ODQ0LCAiaWF0IjoxNjg4MTI3ODQ0LCAianRpIjoiMDFlZTE3NDEtMDA0Ni0xOGE2LWFhMjEtYmQwYTk4ZjYzNzkwIiwgImNsaWVudElkIjoiNDVmMWM1YzgtYTkyZS0xMWVkLWFmYTEtMDI0MmFjMTIwMDAyIiwgInNjb3BlIjoiZGVmYXVsdCJ9.RfKQq2fUZKZFAyjimvsPD3cOzaVWazabmq7b1iKYacqIdNjkvO9CQmu7qdtrVNDmdZ_gHhWLXiGhN4UTSCXv_n1ArDnxTLFBroRS8dxuFBZoD9Mpj10vYFSDDhUfFqjgMqtpr30TpDMfee1wkqB6K757ZSjgCDa0hAbv555GkLdZtRsSgR3xWcxPBsIozqAMFDCWoUCbgTQuA5OiEhhpVco2zv4XLq2sz--VRoBieO12C69KnGRmoLuPtvOayInvrnV96Tbt9fR0fLS2l1nvAdFzVou0SIf9rMZLnURLVQQYE64GR14m-cFRYdUI9vTsFHZBl5w-uCLdzMMofzZaLQ'

{ "uuid":"f4a38d31-21e8-4b5d-9c26-792e6805dd54" }

curl --location 'https://<host>:9095/<basePath>/0.1.0/uuid' \ --header 'Host: <host>' \ --header 'Authorization: Bearer <access-token>'