Component Administration Integration Guide

The Component Administration API provides endpoints for collecting and querying component status, as well as remote invocation API to manage distributed components in Argus.

The API uses role based access control so any interaction will be limited by the requesting user’s role(s).

Please read the General integration guide to learn the general concepts and common data structures used throughout the Argus API.

Tip

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Introduction

The component administration service manages the following concepts:

Component Status

Collection and Querying of the status of distributed containers and components.

Remote Container Management

Endpoints to start, stop, reboot, install and uninstall the distributed component instances.

Remote Method Invocation

Endpoints to invoke specific methods on distributed components, such as updateResources and clearPersistence.

Component Status Collector API is not intended to be used by end users, and is therefore not covered in this integration guide.

Component Status Query API

All interactions the Component Status Query API use the base URL: https://api.mnemonic.no/componentadmin/v2/status

Global System Status

The global system status endpoint returns a top level overview over the status of all configured hosts and instances.

To access this endpoint, the user must have the getComponentStatus permission.

curl -X GET "https://api.mnemonic.no/componentadmin/v2/status" -H "Argus-API-Key: my/api/key" -H "accept: application/json" 

Note

Permission control

For the moment, this endpoint returns the global status, not restricted to the hosts/instances for customers which the user has permissions for.

Host Status

To fetch list of host status:

curl -X GET "https://api.mnemonic.no/componentadmin/v2/status/host?limit=25" -H "Argus-API-Key: my/api/key" -H "accept: application/json" 

Note

The query has a default result limit of 25, use limit/offset to paginate. See Swagger API documentation for list of query parameters.

The advanced search endpoint provides more granular search options:

curl -X POST "https://api.mnemonic.no/componentadmin/v2/status/host/search" -H "Argus-API-Key: my/api/key" -H "accept: application/json" -H "Content-Type: application/json"
-d '{
  "state":["missing"]
}' 

Note

The query has a default result limit of 25, use limit/offset to paginate.

Instance Status

To fetch list of instance status:

curl -X GET "https://api.mnemonic.no/componentadmin/v2/status/instance?limit=25" -H "Argus-API-Key: my/api/key" -H "accept: application/json" 

Note

The query has a default result limit of 25, use limit/offset to paginate. See Swagger API documentation for list of query parameters.

The advanced search endpoint provides more granular search options:

curl -X POST "https://api.mnemonic.no/componentadmin/v2/status/instance/search" -H "Argus-API-Key: my/api/key" -H "accept: application/json" -H "Content-Type: application/json" \
  -d '{
  "includeFlags":["inDowntime"]
}' 

Note

The query has a default result limit of 25, use limit/offset to paginate. See Swagger API documentation for list of query parameters.

Component Status

A configuration instance (container) consists of a number of individual “components” put together into a “container”. To query for the status of individual components:

curl -X POST "https://api.mnemonic.no/componentadmin/v2/status/component/search" -H "Argus-API-Key: my/api/key" -H "accept: application/json"  -H "Content-Type: application/json" \
  -d '{
  "componentType":"no.mnemonic.io.ObjectPusher"
}' 

Note

The query has a default result limit of 25, use limit/offset to paginate. See Swagger API documentation for list of query parameters.

To fetch the status for a single component (by the component UUID):

curl -X GET "https://api.mnemonic.no/componentadmin/v2/status/component/c0224e77-2cd3-4a69-a2ac-c79e33b24ae1" -H "Argus-API-Key: my/api/key" -H "accept: application/json" 

Remote Management API

Listing tasks

For remote management endpoints which run asynchronously, the response will be a task reference. To list completed and ongoing tasks for the current user:

curl -X GET "https://api.mnemonic.no/componentadmin/v1/task" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Note

Tasks in RUNNING state are not yet finished/completed. Polling for updates will allow the user to determine the outcome of the task. Tasks in EXCEPTION, DONE or TIMEOUT state have reached their final state, and will no longer be updated.

Fetching a single task

To fetch a single task:

curl -X GET "https://api.mnemonic.no/componentadmin/v1/task/be15580e-d1ef-4058-9e04-0fa6c555647d" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Starting a container instance

To request the startup of a container instance, the parent (root) container must be started. To request the startup of instance 1123:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/instance/1123/start" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

This operation returns an asynchronous Task, which may not be completed yet. Use the Tasks API to poll for the outcome of this task.

Stopping a container instance

To request the shutdown of a container instance, the instance must be started. To request the shutdown of instance 1123:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/instance/1123/stop" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

This operation returns an asynchronous Task, which may not be completed yet. Use the Tasks API to poll for the outcome of this task.

Rebooting a container instance

To request the orderly shutdown and restart of a container instance, use the reboot endpoint:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/instance/1123/reboot" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

This operation returns an asynchronous Task, which may not be completed yet. Use the Tasks API to poll for the outcome of this task.

Installing a container instance

To request the installation of container instance, use the install endpoint:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/instance/1123/install" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Note

Installing a container does not immediately start it. Installing will add the configuration to the parent container, so it will be started on next boot. To immediately start the container, use the start endpoint.

Uninstalling a container instance

To request the permanent removal of a container instance, use the uninstall endpoint:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/instance/1123/uninstall" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Note

Uninstalling a container does not immediately stop it. Uninstalling will remove the configuration from the parent container, so it will not be started on next boot. To immediately stop the container, use the stop endpoint.

Installing all configured containers on a host

To request the installation of all configured components on a host, use the host installAll endpoint: To install all configurations defined on host 102:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/host/102/installAll" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Note

Installing a container does not immediately start it. Installing will add the configuration to the parent container, so it will be started on next boot. To immediately start all containers on a host, use the host reboot endpoint.

Rebooting all containers on a host

To request the reboot of all containers on a host, use the host reboot endpoint: To reboot all containers defined on host 102:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/host/102/reboot" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Note

Rebooting a host will shut down all running containers on this host. However, it will only trigger startup of installed containers, so any running non-installed containers will not be started again.

Clear all installed containers on a host

To request the removal of all configured containers on a host, use the host cachedconfiguration/clear endpoint:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/host/102/cachedconfigurations/clear" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Note

Uninstalling a container does not immediately stop it. Uninstalling will remove the configuration from the parent container, so it will not be started on next boot. To immediately stop all containers on a host, use the host reboot endpoint after clearing configurations.

Remote Invocation API

The remote invocation APIs contain methods to invoke remote methods on distributed components.

It consists of some specific endpoints, and some general endpoints (/properties, /invoke). The general endpoints should be considered deprecated, and should be avoided. Any known use cases should rather be implemented as specific endpoints, with well-defined return data model.

This integration guide only lists the specific endpoints.

Note

To determine which components to invoke methods on, use the Component Status Query API to locate components. The V1 lookup API is considered deprecated.

Compact Derby persistence database

The Derby persistence database will automatically be compacted on root container reboot after 6 months. To manually initate Derby compaction:

curl -X PUT "https://api.mnemonic.no/componentadmin/v1/host/102/persistence/compact" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

List persistent components

To list all components on a host which have stored state in the host persistence database:

curl -X GET "https://api.mnemonic.no/componentadmin/v1/host/102/persistence" -H "Argus-API-Key: my/api/key" -H "accept: application/json"

Use the containerName and componentName in the result to request clearing of individual components persistence (see below)

Note

The list persistent components endpoint only returns persistence stored in the host global persistence database. Components that have their own persistence database (H2, or a separate Derby DB) are not necessarily listed here.

Clear persistent component

To clear the persistent state of a persistent component, use the containerName and componentName from the list of persistent components, and invoke:

curl -X DELETE "https://api.mnemonic.no/componentadmin/v1/host/102/container/MyContainer/persistence/MyComponent" -H "Argus-API-Key: my/api/key" -H "accept: application/json"