0
£0.00

Introduction

The Mutiny REST API represents the various elements that a Mutiny system contains as parts of a URL path and then allows HTTP verbs to be used to operate on them. In the following documentation :parameter in a URL is used to represent a parameter that the user should fill in. Data is returned as either a JSON document or as a Location header that should be used to retrieve another document. The trailing slash / is required when accessing collections of resources.

When modifying or adding data all parameters are optional except when noted. Standard HTTP status code are used to indicate success and failure (i.e. 200 - OK, 400 - Bad Request, 404 - Resource not found) If there was an error the resource body will contain a textual ID giving more information.

Basic Authentication is used to secure access to the API. Any user of the main Mutiny interface can access the API with the same set of permissions as normal.

Nodes

GET - /api/nodes/?outputFormat=default|concise|idsOnly Returns data about all the nodes on the system as an unsorted array of objects. The outputFormat argument is optional and can be used to change how much data is returned.

GET - /api/nodes/:nodeid

Returns data about a single node as an object.

GET - /api/nodes/:nodeid/snmpInfo/

Returns SNMP info about a single node as an object.

GET - /api/nodes/:nodeid/systemDetails/

Returns system details (os, model etc.) about a single node as an object.

GET - /api/nodes/:nodeid/interfaces/

Returns interface and address data about a single node as an object.

GET - /api/nodes/:nodeid/maintenanceMode/

Returns maintenance mode settings for a single node as an object.

POST - /api/nodes/:nodeid

Updates a single node. The request body should contain a JSON document similar to:-

{
    "label": "New Label",
    "polling": "all|ignore_connectivity|none",
    "address": "New IP v4 address",
    "parentID": "ID of new parent node"
    "maintenanceMode": {
        "state": "off|alerts_only|alerts_events"    // Required if maintenanceMode object is provided.
        "endTime": "2019-09-17T17:30:00Z"   // UTC timestamp formatted according to ISO-8601. Required when turning maintenance mode on
    }
}

All parameters are optional except where noted.

POST - /api/nodes/:nodeid/maintenanceMode

Updates the maintenance mode settings for a single node. The request body should contain a JSON document similar to:-

{
    "state": "off|alerts_only|alerts_events"    // Required.
    "endTime": "2019-09-17T17:30:00Z"   // UTC timestamp formatted according to ISO-8601. Required when turning maintenance mode on
}

DELETE - /api/nodes/:nodeid?deleteDescendants=true|false

Deletes a single node. If deleteDescendants is true then all descendant nodes will also be deleted. Warning: a large amount of data can be deleted very quickly if a high level node and its descendants are deleted.

Views

GET - /api/views/

Returns data about all the views on the system as an unsorted array of objects.

POST - /api/views/

Adds a view to the system. The request body should contain a JSON document similar to:-

{
    "label": "New Label",       // Required
    "published": true|false,
    "parentID": "ID of parent view",
    "childNodes": ["Node ID 1", "Node ID 2", ...]
}

Returns a Location header and a JSON document for the new view.

GET - /api/views/:viewid

Returns data about a single view as an object.

POST - /api/views/:viewid

Updates a single view. The request body should contain a JSON document similar to:-

{
    "label": "New Label",
    "published": true|false,
    "parentID": "ID of parent view"     // Note: Setting parentID to a boolean false moves the view to the top level.
}

DELETE - /api/views/:viewid?deleteContent=true|false

Deletes a view. If deleteContent is true then all of the view's node positions and descendant views will also be deleted.

GET - /api/views/:viewid/childNodes/

Returns an unsorted array of all the child node IDs.

GET - /api/views/:viewid/childNodes/:nodeid

Returns the ID string if it is a child of the view or 404 if it is not.

PUT - /api/views/:viewid/childNodes/:nodeid

Adds the specified node to the specified view.

DELETE - /api/views/:viewid/childNodes/:nodeid

Deletes the specified node from the specified view.

GET - /api/views/:viewid/childViews/

Returns an unsorted array of all the child view IDs.

Tasks

As adding and discovering nodes can take an extended period of time the API represents this by allowing tasks to be created that can be monitored by performing further requests.

GET - /api/tasks/

Returns the current and recent tasks as an unsorted array of objects. Admin users will see all tasks while other users will see the tasks they have created.

POST - /api/tasks/ - Discovery Task

Adds a new discovery task. The request body should contain a JSON document similar to:-

{
    "type": "discovery",                // Required
    "data": {
        "discoveryType": "pingOnly|fullSNMP|traceroute",    // Required
        "label": "Base Label",
        "addresses": ["IPv4 1", "IPv4 2", ...],
        "parentID": "Parent node of discovered nodes.",     // This parameter should normally be omitted for traceroute discovery.
        "allowDuplicates": true|false,      // Ignored for Traceroute discovery,
        "snmpVersion": "v1|v2c",            // Ignored for Ping only discovery, automatic selection if omitted.
        "communityStrings": ["String 1", "String 2", ...]       // Ignored for Ping only discovery, default community strings are always included.
    }
}

Returns a Location header that represents the created task.

POST - /api/tasks/ - Update Task

Adds a new discovery task. The request body should contain a JSON document similar to:-

{
    "type": "update",                // Required
    "data": {
        "nodes": ["Node ID 1", "Node ID 2", ...],
        "action": "update|safe|new|recalc|custom",    // Optional, defaults to "update"
        "snmpVersion": "v1|v2c"            // Optional, automatic selection if omitted.
    }
}

Returns a Location header that represents the created task.

GET - /api/tasks/:taskid

Returns data about a single task as an object.