Using Postman documentation in DotKernel API 3

Starting from version 3.0 DotKernel API provides it’s documentation using Postman.

In this article we will go into the details of creating and maintaining your application’s documentation.

Prerequisites

In order to follow the steps, you will need the following:

  • a working installation of DotKernel API 3
  • download and install Postman from their download page.

TIP: If you don’t have a Postman account, we recommend you to create one. This way Postman is able to backup your workspace in the cloud and synchronize it across multiple devices.

Introduction

For better understanding on how Postman works, we need to run through the “building blocks” of Postman:

  • Workspace: is the main container that holds all your collections, APIs, environments etc
  • Collection: holds all requests and dependencies of a project (for example DotKernel API’s collection containing all requests)
  • Environment: holds a set of environment-specific variables (for example DotKernel API’s environment file cotaining the application URL specific to the development environment)
  • Request: the definition of an API endpoint, including request method, name, description, URL, body, parameters and an example

There are more terms to cover, like Mock servers, Monitors etc but they are not relevant yet in our case.

Importing documentation files

Open Postman (and log in if you have an account), then follow the below steps:

  • open the import modal by clicking File -> Import (or Ctrl + O)
  • inside the modal, make sure you’re on the File tab, then click Upload files
  • navigate to documentation directory of your DotKernel API 3 application and select both of the following files:
    • DotKernel_API.postman_collection.json
    • DotKernel_API.postman_environment.json
  • after clicking Open the modal should show the following:
Select files to import · 2/2 selected
NAME                 FORMAT                         IMPORT AS
DotKernel_API        Postman Collection v2.1        Collection
DotKernel_API        Postman Environment            Environment
  • at the bottom of the import modal, clicking Import will import the selected files and close the modal.

Under My Workspace you should see a tab called Collections. Clicking on it should display all your collections, one of them called DotKernel_API. This collection holds all of the provided requests and serves as the documentation of your application.

DotKernel API 3 collection and environment files ar now imported and ready to use.

For more information on importing files into Postman, please consult their docs.

Interacting with the environment

On the top right corner of Postman, you’ll see the Environment quick look button (it looks like an eye). On it’s left side, there’s a dropdown with all available environments, one of the being called DotKernel_API – click on it to set it as the active environment.

After this, clicking the Environment quick look button will bring up a modal containing all variables found in the environment:

DotKernel_API                                                                              Edit
VARIABLE               INITIAL VALUE                CURRENT_VALUE
APPLICATION_URL        http://localhost:8080        http://localhost:8080

If your application runs on a different host/port, click the Edit button to modify the initial/current value of the APPLICATION_URL variable.

Once in Edit mode, you can also create new variables. You only have to enter the variable name and it’s initial value – current value will be automatically filled in when the variable is used.

Usage

Creating a new request

Inside the collection, right-click on any folder and click Add Request. The new request is automatically opened in a new tab, where you will:

  • enter request name by replacing New Request with a short and descriptive name
  • enter request description (first button under the Environment quick look button)
  • enter request URL – you should use the already existing variable APPLICATION_URL by wrapping it in double curly braces, then append the request path. Example: {{APPLICATION_URL}}/test becomes http://localhost:8080/test when you send the request.
  • select request method
  • (optionally) inspect tabs:
    • Params: manage query parameters
    • Authorization: select authorization type
    • Headers: manage request headers
    • Body: manage request body
    • Pre-request script: provide JavaScript that Postman should run before sending the request
    • Tests: provide JavaScript that Postman should run after receiving the response
    • Settings: manage miscellaneous request settings
  • save the request using the Save button (or Ctrl + S)

Sending a request

Once opened, you can immediately send a request by clicking the Send button.

Optionally, you can save the response as an example (click on Save Response, then select Save as example), so other developers will have a visual representation of the response without making a request. This opens a new tab, where you can manage the example.

Features

The collection provided by DotKernel API 3 comes with some built-in security features.

Global security

Due to the hierarchy of the Collection, all requests are children of the Collection’s root folder, so they automatically inherit it’s Authorization settings. If you edit the Collection’s root folder, you will find the following tabs:

  • Authorization
    • Type is set to Bearer Token
    • Token reads the environment variable ACCESS_TOKEN
  • Pre-request Script: here you can add JavaScript that should run on ALL requests before they run
  • Tests: here you can add JavaScript that should run on ALL requests after their response is returned
  • Variables: here you can manage global variables

To disable this feature globally, set Authorization Type to No Auth or whatever value suits your application’s requirements.

To disable this feature at folder/request level, edit the folder/request and set Type to No Auth under the Authorization tab.

Automatic Token storage

Once an authorization token is re/generated, two environment variables are set/updated:

  • ACCESS_TOKEN: the token that gets sent in the Authorization header
  • REFRESH_TOKEN: the token required to regenerate an ACCESS_TOKEN

This is achieved by applying the following modifications to both Admin/Security and User/Security folders:

  • setting Type to No Auth under the Authorization tab (because the child requests under these folders should not send Authorization header)
  • adding a script under the Tests tab, that reads the response and – if successful – set/updates the above mentioned environment variables

Exporting documentation

TIP: You can inspect your application’s documentation at any moment by clicking on the three horizontal dots (you will find them on hover next to your collection’s name) then click on View documentation.

Exporting collection

Click on the same three horizontal dots, then select Export. You will be presented an Export collection modal asking you to choose the format of the export. Unless specified, choose the recommended version, then click Export. When asked to save the exported file, choose to overwrite your application’s collection file (documentaion/DotKernel_API.postman_collection.json).

Export environment

This step is optional. It is needed only if you made modifications to the environment, else you can skip it.

Start by clicking on the Environment quick look button, then click Edit. Once the edit environment tab opens, locate the three horizontal dots next to the Share button on the right of the Postman window. Click them and select Export. When asked to save the exported file, choose to overwrite your application’s environment file (documentaion/DotKernel_API.postman_environment.json).

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>