Skip to main content

Welcome!

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.

Tutorial layout

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.

The Problem​

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 importing a request library, constructing request bodies, and constructing HTTP requests.

make-request.ts

import axios from 'axios';
let data = JSON.stringify({
quantity: '1,000',
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://petstore.swagger.io/v2/store/order',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
},
data: data,
};

Run the following command in the terminal to execute the code to make a request.

Terminal

ts-node make-request.ts

Oh shoot! It didn't even work, and we got an ambiguous error.

Terminal

data: { code: 500, type: 'unknown', message: 'something bad happened' }

After hours of debugging, we discover that we need to pass the number 1000 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 😤.

make-request.ts

let data = JSON.stringify({
- quantity: '1,000',
+ quantity: 1000,
});

Try again​

Run the following command again.

Terminal

ts-node make-request.ts

Now we should get the expected output.

Terminal

❯ ts-node make-request.ts
Place Order Response: {"id":12,"petId":0,"quantity":1000,"complete":false}

The New Way​

Instead, your customers should be using an SDK.

make-request.ts

import { Petstore } from "petstore";
new Petstore().store.placeOrder({
quantity: 1000
}).then(response => {
console.log("Place Order Response:", response.data);
})

The above SDK example is strongly typed and simplified. But...SDKs are time-consuming to create and maintain.

The Solution: Konfig​

Konfig is a tool for generating SDKs for your API from the OpenAPI Specification and Postman Collection Format.

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 versions.

OpenAPI Specification​

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.

Create a konfig.yaml​

To get started generating a TypeScript SDK, run the following command in the terminal.

Terminal

konfig init

You will be prompted to specify what languages to generate SDKs in.

Language Prompt

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 TypeScript. Press enter to proceed.

Next, you will be prompted with a few questions on how to name your SDK package, the Git repository details, and path to your OpenAPI Specification file.

You can use the following answers for this tutorial:

Terminal

? What is the SDK package name? ... petstore
? What is your Git user ID? petstore
? What is your Git repository name? petstore-sdks
? What is the relative path to your spec? ... api.yaml

About konfig.yaml​

Now we have a konfig.yaml file that includes:

  1. The path to your OpenAPI Specification
konfig.yaml

specPath: api.yaml

  1. Configuration to generate a TypeScript SDK
konfig.yaml

generators:
typescript:
version: 1.0.0
npmName: petstore-typescript-sdk
outputDirectory: typescript
clientName: Petstore
git:
userId: petstore
repoId: petstore-sdks/tree/main/typescript

Now we are ready to generate our TypeScript SDK.

Generate a TypeScript SDK​

To generate your TypeScript SDK, run the following command.

Terminal

konfig generate

You should see the following output.

Terminal

Output directory set to: /tmp/petstore-sdks-out
Generating typescript SDKs... done
Downloading 1 SDKs... done
Deleting output directory... done
Creating output directory... done
Extracting SDKs... done
Deleting contents of existing directory "typescript"... done
Copying Typescript SDK to "typescript"... done
Generating top-level README.md...
Generating top-level README.md... done
Writing top-level LICENSE... done

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.

TypeScript SDK

Finally, let's refactor the make-request.ts implementation to use the generated SDK.

Refactored Implementation​

We refactored make-request.ts to use the SDK you generated. Check your file editor to see the new implementation.

make-request.ts

import { Petstore } from "petstore";
new Petstore().store.placeOrder({
quantity: "1,000"
}).then(response => {
console.log("Place Order Response:", response.data);
})

To build the SDK and run the refactored implementation, execute the following command.

Terminal

cd typescript/ && yarn && yarn build && cd ../ && ts-node make-request.ts

note

We need to run yarn && yarn build to compile the TypeScript SDK to JavaScript.

This time, we caught an error at compile time that tells us quantity should be a number.

Terminal

make-request.ts:5:5 - error TS2322: Type 'string' is not assignable to type 'number'.
5 quantity: '1,000',
~~~~~~~~
typescript/dist/models/order.d.ts:34:5
34 'quantity'?: number;
~~~~~~~~~~
The expected type comes from property 'quantity' which is declared here on type 'Order'

Fixing the compilation error should let us make the request.

Try again​

Run the following command to test the fixed implementation.

Terminal

ts-node make-request.ts

You should see the following output.

Terminal

❯ ts-node make-request.ts
Place Order Response: { id: 14, petId: 0, quantity: 1000, complete: false }

Woohoo, the SDK works!

Recap​

In this tutorial, we learned about the benefits of SDKs, generated an SDK from scratch, and refactored an implementation using the generated SDK 🎉.

Further Reading​

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.