V1 Web API¶

Hello¶

GET /v1/hello¶: Says hello.

Hosts¶

GET /v1/hosts¶

Returns all hosts.

Return type:	list(`Host`)

POST /v1/hosts¶

Create a new host.

Parameters:	data (`Host`) – a host within the request body.
Return type:	`Host`

GET /v1/hosts/(host_name)¶

Returns a specific host.

Return type:	`Host`

PUT /v1/hosts/(host_name)¶

Modify this host.

Parameters:	data (`Host`) – a host within the request body.

DELETE /v1/hosts/(host_name)¶: Delete this host.

GET /v1/hosts/(host_name)/services¶

Returns all services assocaited with this host.

Return type:	list(`Service`)

GET /v1/hosts/(host_name)/services/(service_name)/(service_description)¶

Returns a specific service.

Return type:	`Service`

POST /v1/hosts/(host_name)/results¶

Submit a new check result.

Parameters:	data (`CheckResult`) – a check result within the request body.

POST /v1/hosts/(host_name)/services/(service_description)/results¶

Submit a new check result.

Parameters:	data (`CheckResult`) – a check result within the request body.

type CheckResult¶

Data samples:

Json

{
    "output": "CPU Usage 98%|c[cpu]=98%;80;95;0;100", 
    "return_code": 0, 
    "time_stamp": "1409087486"
}

XML

<value>
  <time_stamp>1409087486</time_stamp>
  <return_code>0</return_code>
  <output>CPU Usage 98%|c[cpu]=98%;80;95;0;100</output>
</value>

output¶

Type:	unicode

The output of the check.

return_code¶

Type:	int

The return code of the check.

time_stamp¶

Type:	unicode

The time the check was executed. Defaults to now.

type Host¶

Data samples:

Json

{
    "address": "192.168.1.254", 
    "check_period": "24x7", 
    "contact_groups": "router-admins", 
    "contacts": "admin,carl", 
    "custom_fields": {
        "OS_AUTH_URL": "http://localhost:8080/v2"
    }, 
    "host_name": "bogus-router", 
    "max_check_attempts": 5, 
    "notification_interval": 30, 
    "notification_period": "24x7", 
    "use": "generic-host"
}

XML

<value>
  <host_name>bogus-router</host_name>
  <address>192.168.1.254</address>
  <max_check_attempts>5</max_check_attempts>
  <check_period>24x7</check_period>
  <contacts>admin,carl</contacts>
  <contact_groups>router-admins</contact_groups>
  <notification_interval>30</notification_interval>
  <notification_period>24x7</notification_period>
  <use>generic-host</use>
  <custom_fields>
    <item>
      <key>OS_AUTH_URL</key>
      <value>http://localhost:8080/v2</value>
    </item>
  </custom_fields>
</value>

address¶

Type:	unicode

The address of the host. Normally, this is an IP address.

check_period¶

Type:	unicode

The time period during which active checks of this host can be made.

contact_groups¶

Type:	unicode

List of the short names of the contact groups that should be notified

contacts¶

Type:	unicode

A list of the short names of the contacts that should be notified.

custom_fields¶

Type:	dict(unicode: unicode)

Custom fields for the host

host_name¶

Type:	unicode

The name of the host

use¶

Type:	unicode

The template to use for this host

Services¶

GET /v1/services¶

Returns all services.

Return type:	list(`Service`)

POST /v1/services¶

Create a new service.

Parameters:	data (`Service`) – a service within the request body.
Return type:	`Service`

type Service¶

Data samples:

Json

{
    "check_command": "check-disk!/dev/sdb1", 
    "check_interval": 5, 
    "check_period": "24x7", 
    "contact_groups": "linux-admins", 
    "contacts": "surveil-ptl,surveil-bob", 
    "host_name": "sample-server", 
    "max_check_attempts": 5, 
    "notification_interval": 3, 
    "notification_period": "24x7", 
    "retry_interval": 3, 
    "service_description": "check-disk-sdb"
}

XML

<value>
  <host_name>sample-server</host_name>
  <service_description>check-disk-sdb</service_description>
  <check_command>check-disk!/dev/sdb1</check_command>
  <max_check_attempts>5</max_check_attempts>
  <check_interval>5</check_interval>
  <retry_interval>3</retry_interval>
  <check_period>24x7</check_period>
  <notification_interval>3</notification_interval>
  <notification_period>24x7</notification_period>
  <contacts>surveil-ptl,surveil-bob</contacts>
  <contact_groups>linux-admins</contact_groups>
</value>

Commands¶

GET /v1/commands¶

Returns all commands.

Return type:	list(`Command`)

POST /v1/commands¶

Create a new command.

Parameters:	data (`Command`) – a command within the request body.
Return type:	`Command`

GET /v1/commands/(command_name)¶

Returns a specific command.

Return type:	`Command`

PUT /v1/commands/(command_name)¶

Modify this command.

Parameters:	data (`Command`) – a command within the request body.

DELETE /v1/commands/(command_name)¶: Delete this command.

type Command¶

Data samples:

Json

{
    "command_line": "/bin/check_http", 
    "command_name": "check_http"
}

XML

<value>
  <command_name>check_http</command_name>
  <command_line>/bin/check_http</command_line>
</value>

command_line¶

Type:	unicode

This directive is used to define what is actually executed by Shinken

command_name¶

Type:	unicode

The name of the command