JSON Network API

A JSON Network Location API can be used to create, update, or delete Network Locations in the system.

A JSON Network API helps you automate changes to your organization's Network Locations. It is particularly helpful for large organizations with complex or frequently changing Networks.

You can use a JSON Network API to:

• Export a list of your organization's Network Locations in JSON format. You can export all Locations in your organization or individual Locations.

• Update every part of an existing Network Location.
• Create new Network Locations. 
• Delete existing Network Locations.

How does it work? 

KaiNexus provides an endpoint where you can access Network information. To make a call, you will need an API Key and an API tool. 

Authentication

API Keys are used for authenticating calls to KaiNexus API. Check out this article for instructions on how you can find your organization's API Keys and copy them to your clipboard. 

If you are using Postman, select Basic Auth as the Authorization Type.

• Enter "api" as the username.
• Enter the API Key as the password. 

Exporting Network Locations

After authentication, you can make your first JSON Network API call. We recommend starting with a GET request to retrieve a list of Network Locations in proper JSON format. This will be useful as a reference for the correct JSON format when updating or creating Locations. 

KaiNexus's Network Export APIs allow you to export:

• A list of all Network Locations in the organization
• An individual Network Location

To export a list of all Network Locations, make a GET request to this URL:

https://api.kainexus.com/api/public/v1/json/networkLocationList

To export an individual Network Location, execute a GET request to this URL:

https://api.kainexus.com/api/public/v1/json/networkLocation?id=XXXXX

• Replace XXXXX with the Network Location's ID.
• You can find a Location's ID by adding an ID column to the Network administration page.

Importing and updating Network Locations

After you have exported Network Locations in JSON format, you can use that code as a reference to update or create new Locations.

To update or create multiple Network Locations, execute a PUT request to this URL:

https://api.kainexus.com/api/public/v1/json/networkLocationList

Here is an example of the JSON format for importing a list of Network Location: 

{
    "items": [
        {
            "id": 5,
            "name": "KaiNexus Corporation",
            "levelType": {
                "id": 4,
                "name": "System"
            }
        },
        {
            "id": 29,
            "name": "Corporate",
            "levelType": {
                "id": 1,
                "name": "Department"
            },
            "parent": {
                "id": 5,
                "name": "KaiNexus Corporation"
            }
        },
        {
            "id": 16,
            "name": "Accounting",
            "levelType": {
                "id": 12,
                "name": "Administration"
            },
            "parent": {
                "id": 29,
                "name": "Corporate"
            }
        }
    ]
}

To update or create a single Network Location, execute a PUT request to the following URL:

https://api.kainexus.com/api/public/v1/json/networkLocation

Here is an example of the JSON format for importing a single Network Location: 

{
    "item": {
        "name": "Corporate",
        "levelType": {
            "name": "Department"
        },
        "parent": {
            "name": "KaiNexus"
        }
    }
}

The API will recognize whether the Network Location(s) in your request already exist or if a new Location needs to be created.

• If an ID is provided, the existing Network Location with that ID will be updated.
• If an ID is not provided, but a Network Location exists with the name specified, the Network Location with that name will be updated.
• If no ID is specified and no Location with the specified name exists, a new Network Location with that name will be created.

Deleting Network Locations

To delete a Network Location, include "delete": true in the request.

In the following example, the Location with the ID 683 will be deleted.

{
    "item": {
        "id": 683,
        "delete": true
    }
}

What data is supported by JSON Network API?

The following table describes which data is supported in JSON Network API calls. These keys will be included in exports.

Example: Curl Script for exporting a list of Network Locations

curl -s -k --user api:APIKEY https://api.kainexus.com/api/public/v1/json/networkLocationList -X GET | jq | tee networkLocationList.json

• Replace APIKEY with the API Key generated in KaiNexus

Error Messages

Failed updates will return an error containing a code and message that can be referenced below: