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

To update or create an individual Network Location, execute a PUT request to this URL:

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

The API will recognize whether the Network Locations 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
    }
}

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

Example: JSON format for importing a list of Network Locations:

{
    "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"
            }
        }
    ]
}

Example: JSON format for importing an individual Network Location

{
    "item": {
        "id": 29,
        "name": "Corporate",
        "levelType": {
            "id": 1,
            "name": "Department"
        },
        "parent": {
            "id": 5,
            "name": "KaiNexus Corporation"
        }
    }
}

Error Messages

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