Get links (API v2)

This is an experimental request and may change in future releases.

Request that returns links in the system. You can pass filters and other options in the request body to customize the output.

Request

HTTP Request

POST /node/api/v2/getLinks

Permissions

linkPermissions

Body parameters

Parameter Type Description

filter

Object

Filter applied to the list of links.

filter.source

Array<String>

Array of object IDs. Links that start from these objects will be included in the response.

filter.target

Array<String>

Array of object IDs. Links that target these objects will be included in the response.

filter.state_id

Array<String>

Array of state IDs. Links that are currently in these states will be included in the response.

filter.class_id

Array<String>

Array of class IDs. Links of that class will be included in the response.

filter.id

Array<String>

Array of link IDs. Links with those IDs will be included in the response.

filter.tags

Array<String>

Array of tag IDs. Links that are tagged with the specified tags will be included in the response.

fields

Array<String>

Names of fields that will be included in the response.

order

Array

Array of fields by which this request sorts the links. By default, the included field is sorted in ascending order. If the field has a ! character before its name, the list will be sorted in descending order.

limit

Integer

Maximum amount of links included in the response.

offset

Integer

How many records this request should skip.

Request body

Request body allows you to configure the output of this request. You can filter and sort the returned links, specify which fields are returned and use server-side pagination with the limit and offset parameters.

Request body is optional. If the request body is empty, the response will contain all links in the system and include the following fields:

  • source

  • target

  • class_id

  • state_id

  • last_state_update

  • source_name

  • target_name

  • name

  • id

{
    "filter": {
        "source": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" // source object ID
        ],
        "target": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ], // target object ID
        "state_id": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ], // link state ID
        "class_id": [
            "5926a84355687d6bb793dd88",
            "5926a84355687d6bb793dd9c"
        ], // link class ID
        "id": [
            11,
            14,
            "629709900618240e2b83a18e",
            "626f935fbad91064e16e57b7",
            "626ed4bcbad91064e16e521a"
        ], // link ID
        "tags": [
            "63c6b25aee2fca5eb640456c",
            "6401bbb8b5208c0a9aad17cc"
        ] // tag ID
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],  // names of included fields
    "order": [
        "class_id",
        "!id"], // list is sorted by class_id in ascending order, then by id in descending order
    "limit": 5,
    "offset": 5
}

Response

Response contains a list of links stored in the items array and the number of returned links in the count field.

The list of returned links depends on the filters and settings passed in the request body.

Examples

Request

  • Bash

  • JavaScript

  • NodeJS

  • Python

login=<...>
password=<...>
saymon_hostname=<...>
url=https://$saymon_hostname/node/api/v2/getLinks

curl -X POST $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "filter":{
        "class_id": [3, 35]
    },
    "fields": ["class_id", "name", "source_name", "target_name"],
    "order": ["class_id", "!id"]
}
EOF
let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/v2/getLinks";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Content-Type", "application/json");
headers.append("Authorization", auth);

let data = JSON.stringify({
    "filter":{
        "class_id": [3, 35]
    },
    "fields": ["class_id", "name", "source_name", "target_name"],
    "order": ["class_id", "!id"]
});

let requestOptions = {
    method: "POST",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/v2/getLinks";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "POST",
    "hostname": saymonHostname,
    "headers": {
        "Authorization": auth,
        "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
    "filter":{
        "class_id": [3, 35]
    },
    "fields": ["class_id", "name", "source_name", "target_name"],
    "order": ["class_id", "!id"]
});

req.write(data);
req.end();
import requests

login = <...>
password = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/v2/getLinks"

body = {
    "filter":{
        "class_id": [3, 35]
    },
    "fields": ["class_id", "name", "source_name", "target_name"],
    "order": ["class_id", "!id"]
}

response = requests.request("POST", url, json=body, auth=(login, password))
print(response.text)

Response

{
    "count": 1264,
    "items": [
        {
            "class_id": 35,
            "source_name": "Host 1",
            "target_name": "Host 2",
            "name": "Host 1 - Host 2",
            "id": 282
        },
        ...
    ]
}