Generating API Calls

Use Postman or another API application to test your connection and start making new API calls

After you have completed all the necessary set up work in KaiNexus, you can start making API calls in your API application of choice. If you need any help giving users the API Administrator Permission, creating an API Key, or finding the ID of the KaiNexus List you are working with, we recommend returning to Getting Started with API. 

This article will go over the basics for generating an API call to KaiNexus, including:

• Supported API Requests
• The URLs used for API Requests
• Testing your API connection
• Making an API call
• Status Codes and Troubleshooting
• Pagination
• Rate Limit

Supported API Requests

You can make PUT and GET requests to KaiNexus API. 

• GET requests are used to retrieve information from KaiNexus. 
• PUT requests are used to add or update information in KaiNexus. 

URLs used in API Requests

You will utilize a different variations of the api.kainexus.com/api/v1 URL to make API calls depending on the type of call you want to perform.

Changing whether a GET or PUT request is sent to this URL will determine whether you export or update information. 

People API

• Use the following URL when referencing all users in the organization in your API call:
  https://api.kainexus.com/api/public/v1/json/userList

• Use the following URL when referencing an individual user in your API call:
  https://api.kainexus.com/api/public/v1/json/user?id=XXXXX
  
  • Replace XXXXX with the User ID

• Use the following URL when referencing a specific List of users in your API call: 
  https://api.kainexus.com/api/public/v1/json/userList?id=XXXXXX
  
  • Replace XXXXX with the User List ID

Item API

• Use the following URL when referencing an individual Item in your API call: https://api.kainexus.com/api/public/v1/json/item?id=XXXXXX
  • Replace XXXXX with the Item ID number. 

• Use the following URL when referencing a List of Items in your API call: 
  https://api.kainexus.com/api/public/v1/json/itemList?id=XXXXXX
  
  • Replace XXXXX with the Item List ID.
• Use the following URL when creating new Items in your API call:
  https://api.kainexus.com/api/public/v1/json/item

Chart API

• Use the following URL when updating Charts using JSON: 
  https://api.kainexus.com/api/public/v1/json/item?fullSync=true
• Use the following URL when exporting Charts using JSON:
  https://api.kainexus.com/api/public/v1/json/item?id= XXXXX&includeCharts=true
  • Replace XXXXX with the Item ID
  • Replace "item" with "itemList" when working with a List of Charts. 

• Use the following URL when importing Charts using XLSX format:
  https://api.kainexus.com/api/public/v1/excel/multiChartImport
• Use the following URL when exporting a List of Charts in XLSX format:
  https://api.kainexus.com/api/public/v1/excel/chartList?id=XXXXX

Network API

• Use the following URL when referencing all Network Locations in the organization in your API call:
  https://api.kainexus.com/api/public/v1/json/networkLocationList
• Use the following URL when referencing an individual Network Location in your API call:
  https://api.kainexus.com/api/public/v1/json/networkLocation?id=XXXXX
  
  • Replace XXXXX with the Network ID
  • Remove "?id=XXXXX" if you are adding one new Location

API Calls to Sandbox Environment

You may want to test your API call before affecting data in your organization's main production environment. To make API calls to your organization's sandbox environment:

• Replace "api.kainexus.com" with "sandbox.kainexus.com" in your request's URL. 

Testing your API connection

We recommend testing the API connection to ensure your API Key returns the correct values and the data received during the call is correct. 

Testing is especially important for large organizations that utilize firewalls and other security measures that might block the API connection. 

You can either test the API connection through your browser or test the connection through an application such as Postman. 

• To test the API connection through your browser:
  • Visit the URL corresponding to the type of API call you want to perform. For example, to test a JSON Item Export call, visit the following URL: https://api.kainexus.com/api/public/v1/json/ideaList?id=XXXXX
  • Replace the "XXXXX" at the end of the URL with the unique identifier for the Card or List you are targeting. 
  • Your browser will ask for a user name and password. 
    • The username will always be “api”. 
    • The password will be your selected API Key found in the Admin section of KaiNexus.
  • If successful, your Item List will returned in JSON format. 
• To test the API connection through Postman:
  • Open the application, and select Basic Auth for the Authorization Type:
    • Username: api
    • The password will be your selected API Key found in the Admin section of KaiNexus. 
  • Select GET as your request type. 
  • Enter the URL corresponding to the type of API Call you want to perform in the request. For example, to test a JSON Item Export API call, enter the following URL:
    https://api.kainexus.com/api/public/v1/json/itemList?id=XXXXXX
  • Replace the "XXXXX" at the end of the URL with the unique identifier for the Card or List you are targeting. 
  • If successful, a response with your Item List in JSON format will be returned. 

Making new API Calls 

You can use your application of choice to call the API. We recommend using Postman, but Curl is another application we see used as well. 

Using Postman

Postman is a free platform that you can use to make API calls. Follow these steps to make an API call in Postman:

• Enter your Authorization.
  • In Authorization, select Basic Auth as the Authorization Type. 
  • Enter "api" for the username. 
  • Enter your API Key for the password. 

• In the request bar, select GET to retrieve information from KaiNexus or PUT to update information in KaiNexus. 
  
  • If you are making a PUT request, you must enter the information you want to update in the request Body using JSON format. An easy way to make sure you are using the correct format is to first GET the User, Item, Chart, or Network information you want to update. This will give you the correct JSON format. Make the changes you want, and then add it to the body in a new PUT request. 
• Enter or paste the URL corresponding to the type of API call you want to make. 
• Select Send. 

Using Curl

Example of Curl script that downloads a specified List to excel.xls:

curl -s -D - --user api:APIKEY https://api.kainexus.com/api/public/v1/excel/ideaList?id=xxxxxx --output excel.xlsx

• Replace APIKEY with the API Key generated in KaiNexus
• Replace xxxxx with the ID of the List or Card you are referencing data from. 
• The output file name is customizable. 
• The script will print the http headers (including status code) to the console.

Here is a console print example:

HTTP/1.1 200

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Pragma: no-cache

Expires: 0

X-Frame-Options: DENY

X-Application-Context: application:dev:8080

Content-disposition: attachment; filename="KaiNexus-Export-xxxxxx-11132017-161233.xlsx"

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Transfer-Encoding: chunked

Status Codes

After your API request is sent, you will receive a Status Code that informs you whether the request was successful or if there was an error. 

Important codes include:

• 200: The request was successful. This is what you are looking for. 
• 401: Authorization error. Confirm your API Key is correct and it has permission to access the information you are requesting. 
• 404: Connection error. Confirm you are using the correct URL. 
• 400: Another type of error. View the response for more information.
  • Check whether the syntax in the body of your request is correct.

• • Check that you have the correct ID number. 

Pagination

For Item exports, two parameters can be specified to control paging:

• offset: The (zero-based) offset of the first Item in the collection to return - optional - defaults to 0.
• limit: The max number of Items to return - optional - defaults to 30000. It cannot exceed 30000.

For User Exports, two parameters can be specified to control paging:

• offset: the (zero-based_ offset of the first item in the collection to return -optional- defaults to 0
• limit: the max number of items to return - optional- defaults to 20000. It cannot exceed 20000. 

Rate Limit

The KaiNexus API enforces rate limits to ensure system stability. We recommend limiting your rate of API calls to no more than 5 calls per minute. 

Recommended Reading:

Now that you understand the basics of generating KaiNexus API calls, we recommend checking out our documentation for the specific type of API call your organization will be using. 

• Item Export API
• Item Update API
• Item Creation API
• People API
• Network API
• Chart Export API
  • JSON
  • XLSX
• Chart Update API
  • JSON
  • XLSX