This is the interactive tutorial for Konfig.
How to use this tutorial
On the left are the directions for the tutorial.
On the right is an interactive development environment to execute commands and edit files.
At the top of the development environment, you will see a file editor.
And at the bottom of the development environment, you will see a terminal.
Each section will present a new topic for generating SDKs with Konfig. Later steps require the completion of earlier ones, so you must go from start to finish.
Click the button below to go to the next step.
APIs can be difficult to integrate—especially when an API has hundreds of operations and data models. Nowadays, API-first companies publish SDKs because it accelerates integration and converts more customers.
The Old Way
This is what it looks like to integrate with your API without an SDK. We are manually, , and .
Run the following command in the terminal to execute the code to make a request.
Oh shoot! It didn't even work, and we got an ambiguous error.
After hours of debugging, we discover that we need to pass the number
instead of the string
"1,000". Debugging these sorts of issues is frustrating
and leads to a longer time to value and ultimately lower conversions 😤.
The Solution: Konfig
To generate SDKs, we created a CLI which has been installed in your development environment.
To control how the SDKs are generated, we created a file type called
konfig.yaml. This file specifies things such as target languages or SDK
For this tutorial, we are using an OpenAPI Specification for an API that manages a Petstore. You can examine the API in the development environment.
To get started generating a TypeScript SDK, run the following command in the terminal.
You will be prompted to specify what languages to generate SDKs in.
For this demo, we will only generate a TypeScript SDK. Type
a to de-select all
languages. Then use the down arrow and
space to select
enter to proceed.
Next, you will be prompted with a few questions on how to, , and .
You can use the following answers for this tutorial:
Now we have a
konfig.yaml file that includes:
- The path to your OpenAPI Specification
- Configuration to generate a TypeScript SDK
Now we are ready to generate our TypeScript SDK.
Generate a TypeScript SDK
To generate your TypeScript SDK, run the following command.
You should see the following output.
The Generated SDK
Konfig's generated SDKs are crafted to feel ergonomic and include comprehensive documentation so your customers are delighted throughout the integration.
Take a look at the
typescript/ folder to see the generated code.
Finally, let's refactor the
make-request.ts implementation to use the generated SDK.
make-request.ts to use the SDK you generated. Check your file
editor to see the new implementation.
Toand , execute the following command.
We need to run
This time, we caught an error at compile time that tells us
quantity should be a number.
Fixing the compilation error should let us make the request.
Run the following command to test the fixed implementation.
You should see the following output.
Woohoo, the SDK works!
In this tutorial, we learned about the benefits of SDKs, generated an SDK from scratch, and refactored an implementation using the generated SDK 🎉.
When doing this on a real API you will need to make modifications to your OpenAPI Specification to generate high-quality SDKs. Konfig also makes this easy through its lint and fix utilities. You may also want to setup Continuous Deployment through GitHub Action or polling. And sometimes it's also necessary to add business logic to your SDKs, which is also made easy by Konfig through our support for customization.