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.
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.
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
Ctrl + O)
- inside the modal, make sure you’re on the
Filetab, then click
- navigate to
documentationdirectory of your DotKernel API 3 application and select both of the following files:
- after clicking
Openthe 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
Importwill 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
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.
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_URLby wrapping it in double curly braces, then append the request path. Example:
http://localhost:8080/testwhen 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
- 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.
The collection provided by DotKernel API 3 comes with some built-in security features.
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:
- Type is set to
- Token reads the environment variable
- Type is set to
- 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 Authunder 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
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.
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).
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).