Getting Started with Postman Collections

Postman is a great way to document and save example requests for your API. Konfig supports generating SDKs from Postman Collections through the Postman Collection Format. In this tutorial, we will walk through the steps for you to generate a TypeScript, Java, and Python SDK from a Postman Collection.

How does it work?

Konfig infers the interface of your API from request and response examples in your Postman Collection. Konfig then intelligently creates a high-quality OAS which is then used to generate SDKs.

Generating SDKs from Postman Collections with Konfig

Install CLI

To install Konfig's CLI run the following command:

npm

yarn

_10

npm install -g konfig-cli

System Requirement

Konfig's CLI requires Node 14+ to be setup on your machine.

Create a directory for SDKs

CLI

_10

mkdir postman-sdks

_10

cd postman-sdks

Prepare your Postman Collection

Every operation in your Collection should have more example responses saved before exporting for better SDKs.

Organize requests into folders

Placing requests under folders will help Konfig group operations together in the generated SDKs.

Parameterize request paths

Hard-coded values for variables such as path parameters will not be correctly inferred as variables in the generated SDKs. For example, if you have a request path /project/1234, the SDKs will not know that 1234 is a variable.

Instead of /project/1234, use /project/:projectId.

Send Request

Click Send to retrieve an example response. You can repeat these steps for different inputs to save multiple example responses. The more requests and responses saved in the Collection, the better your SDKs will be.

Click "Save as example"

Save the retrieved response as an example in your collection.

Example should be shown in the menu

You should see a list of examples saved in the left-side menu. Repeat this process for all your operations with as many examples as possible.

Add [required] to description of required parameters

For any required parameters, add [required] to the description. This will ensure that the SDKs will throw an error if the required parameter is not provided.

Set preview language of response body

Set the preview language of the response body to JSON or Text to ensure that the response body schema type is inferred correctly in the generated SDKs. If you want a raw string to be returned from your endpoint then thoose Text. If you want the response body to be inferred an "object" type schema, then choose JSON.

Export Postman Collection

Click the button on your Postman Collection and click "export":

Choose Collection v2.1 and click Export.

Initialize SDK directory

Move the exported Postman Collection to the SDK directory

Copy your exported Postman Collection to your SDK directory.

CLI

_10

cp ~/Downloads/Requests.postman_collection.json ~/postman-sdks

Convert your Postman Collection to an OpenAPI Specification

Use Konfig's p2o command to convert your Postman Collection to an OpenAPI Specification .yaml file.

CLI

_10

konfig p2o -p Requests.postman_collection.json -o api.yaml

Run konfig init

Use Konfig's init command to create your konfig.yaml file.

_10

konfig init

Konfig will download the necessary setup files and ask a series of questions to fill in your konfig.yaml file. When asked what languages to generate, select Java, Python, and TypeScript for this tutorial.

CLI

_10

Downloaded version 1.1.123 of https://www.npmjs.com/package/konfig-spectral-ruleset

_10

Downloading Konfig's lint rules... done

_10

Setting up Spectral... done

_10

Setting up VScode settings.json... done

_10

? Select languages to generate SDKs for: Java, Python, TypeScript

_10

? What is your domain? (ex. acme.com) konfigthis.com

_10

? What is the SDK package name? Use hyphens to separate words (ex. acme-web) konfig

_10

? What is your Git user ID? konfig-dev

_10

? What is your Git repository name? postman-getting-started-sdks

_10

? What is the relative path to your spec? (ie. "<CURRENT_DIRECTORY>/path/to/api.yaml") api.yaml

Once finished, you will see a bunch of files automatically added to your directory.

_14

tree -a

_14

.

_14

├── .konfig

_14

│ ├── ruleset-version

_14

│ └── ruleset.js

_14

├── .spectral.yaml

_14

├── .vscode

_14

│ ├── extensions.json

_14

│ └── settings.json

_14

├── Requests.postman_collection.json

_14

├── api.yaml

_14

└── konfig.yaml

_14

_14

2 directories, 8 files

The konfig.yaml file includes all the necessary configurations to generate SDKs for your Postman Collection. You can read more about the schema of konfig.yaml here.

konfig.yaml

_31

# yaml-language-server: $schema=https://unpkg.com/konfig-lib@latest/konfig-yaml.schema.json

_31

_31

outputDirectory: /tmp/konfig-sdks-out

_31

specPath: api.yaml

_31

generators:

_31

java:

_31

version: 1.0.0

_31

groupId: com.konfigthis

_31

artifactId: konfig-java-sdk

_31

clientName: Konfig

_31

outputDirectory: java

_31

git:

_31

userId: konfig-dev

_31

repoId: postman-getting-started-sdks/tree/main/java

_31

python:

_31

version: 1.0.0

_31

packageName: konfig_client

_31

projectName: konfig-python-sdk

_31

outputDirectory: python

_31

clientName: Konfig

_31

git:

_31

userId: konfig-dev

_31

repoId: postman-getting-started-sdks/tree/main/python

_31

typescript:

_31

version: 1.0.0

_31

npmName: konfig-typescript-sdk

_31

outputDirectory: typescript

_31

clientName: Konfig

_31

git:

_31

userId: konfig-dev

_31

repoId: postman-getting-started-sdks/tree/main/typescript

Create high-quality OAS

Use the fix command to create a high-quality OAS. This will override your OAS with a new version that is prepared for generating high-quality SDKs.

CLI

_10

konfig fix

You will be asked a series of questions regarding what to name particular operations and how to group them.

CLI

_806

┌ Improper Tag Detected ────────────────────────────────────────────┐

_806

│ │

_806

│ Detected improperly named Tag "users > {user_id}" │

_806

│ https://konfigthis.com/docs/lint-rules#tag-naming-convention" │

_806

│ │

_806

└───────────────────────────────────────────────────────────────────┘

_806

? Select existing tag: users

_806

┌──── Summary ────┐

_806

│ │

_806

│ Delete User │

_806

│ │

_806

└─────────────────┘

_806

┌──────── Path - Method ────────┐

_806

│ │

_806

│ /users/{user_id} - DELETE │

_806

│ │

_806

└───────────────────────────────┘

_806

? Enter operation ID: Users_delete

_806

┌── Summary ───┐

_806

│ │

_806

│ Get User │

_806

│ │

_806

└──────────────┘

_806

┌────── Path - Method ───────┐

_806

│ │

Generate SDKs

Run konfig generate to generate SDKs.

_10

konfig generate

You will see the following output when generating SDKs.

note

It can take a few minutes to finish generating SDKs.

_14

Output directory set to: /tmp/konfig-sdks-out

_14

Generating java, python, typescript SDKs... done

_14

Downloading 3 SDKs... done

_14

Deleting output directory... done

_14

Creating output directory... done

_14

Extracting SDKs... done

_14

Deleting contents of existing directory "java"... done

_14

Copying Java SDK to "java"... done

_14

Deleting contents of existing directory "python"... done

_14

Copying Python SDK to "python"... done

_14

Deleting contents of existing directory "typescript"... done

_14

Copying Typescript SDK to "typescript"... done

_14

Generating top-level README.md... done

_14

Writing top-level LICENSE... done

Once finished, you should see three SDKs added to your directory.

CLI

_56

❯ tree -L 2

_56

.

_56

├── LICENSE

_56

├── README.md

_56

├── Requests.postman_collection.json

_56

├── api.yaml

_56

├── flows

_56

│ ├── java

_56

│ ├── python

_56

│ └── typescript

_56

├── java

_56

│ ├── README.md

_56

│ ├── api

_56

│ ├── build.gradle

_56

│ ├── build.sbt

_56

│ ├── docs

_56

│ ├── gradle

_56

│ ├── gradle.properties

_56

│ ├── gradlew

_56

│ ├── gradlew.bat

_56

│ ├── pom.xml

_56

│ ├── settings.gradle

_56

│ └── src

_56

├── konfig.yaml

_56

├── python

_56

│ ├── LICENSE

_56

│ ├── README.md

_56

│ ├── docs

_56

│ ├── konfig_client

_56

│ ├── poetry.lock

_56

│ ├── pyproject.toml

_56

│ ├── setup.cfg

_56

│ ├── setup.py

_56

│ └── test

_56

└── typescript

_56

├── README.md

_56

├── api

_56

├── api.ts

_56

├── base.ts

_56

├── client-custom.ts

_56

├── client.ts

_56

├── common.ts

_56

├── configuration.ts

_56

├── docs

_56

├── index.ts

_56

├── jest.config.ts

_56

├── models

_56

├── package.json

_56

├── pagination

_56

├── requestAfterHook.ts

_56

├── requestBeforeHook.ts

_56

├── tsconfig.json

_56

├── tsconfig.test.json

_56

└── yarn.lock

_56

_56

18 directories, 34 files

Example Output

You can explore the example output of this tutorial here: https://github.com/konfig-dev/postman-getting-started-sdks.

Next Steps

To update your SDKs simply repeat the steps from export to generation.

Konfig's SDKs are highly customizable in case you need to add to your SDKs. Once you are finished developing your SDKs, you can also test, publish, and automate your entire SDK workflow with Konfig.