Introduction
Welcome to the documention of the JSON API of Flapjack.
See the flapjack-diner RubyGem which provides a Ruby consumer of this API.
Required HTTP Headers
JSON API requires the Content-Type header to be set as follows. The Accept header is not required but recommended when the client expects a JSON response body.
GET
Accept: application/vnd.api+json
POST
Content-Type: application/json or
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
PATCH
Content-Type: application/json-patch+json
Accept: application/vnd.api+json
DELETE
No specific headers required.
Relevant Specifications
Contacts
The Contact resource has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| id | String | |
| first_name | String | |
| last_name | String | |
| String | ||
| timezone | String | |
| tags | Array[String] |
Create contacts
Creates one or more contacts, returns an array containing the ids of the created contacts. The ordering is preserved, so if you POST an array of three contacts, the resulting array of ids will be in the same order as the posted data; the first item of the POSTed array will correspond to the first id in the resulting array, etc.
Contact ids may optionally be supplied. If it is omitted, then a UUID will be created.
If an id is supplied in any of the included contacts, and any of them clash with an existing contact, the whole request will be rejected and no changes will be written.
curl -w 'response: %{http_code} \n' -X POST -H "Content-Type: application/vnd.api+json" -d \
'{
"contacts": [
{
"first_name": "Ada",
"last_name": "Lovelace",
"email": "ada@example.com",
"timezone": "Europe/London",
"tags": [
"legend",
"first computer programmer"
]
}
]
}' \
http://localhost:3081/contacts
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_contacts({
:first_name => "Ada",
:last_name => "Lovelace",
:email => "ada@example.com"
})
The above command returns JSON structured like this:
["cd40283b-023e-43e2-a79c-1910415afdc2"]
HTTP Request
POST /contacts
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| contacts | Array[Contact] | An array of Contact resources to create. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 201 | The submitted contacts were created successfully. |
| 405 | Error The submitted contact data was not sent with the JSONAPI MIME type application/vnd.api+json. |
| 409 | Error Contacts with ids matching those submitted were found. |
| 422 | Error The submitted contact data did not conform to the provided specification. |
Get contacts
If no contact ids are provided then all contacts will be returned; if contact ids are provided then only the contacts matching those ids will be returned.
curl http://localhost:3081/contacts
# or
curl http://localhost:3081/contacts/1
# or
curl http://localhost:3081/contacts/21,22
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.contacts
# or
Flapjack::Diner.contacts('21')
# or
Flapjack::Diner.contacts('21', '22')
The commands return JSON structured like this, which is broken up by Flapjack::Diner into its constituent hashes:
{
"contacts": [
{
"id": "21",
"first_name": "Ada",
"last_name": "Lovelace",
"email": "ada@example.com",
"timezone": "Europe/London",
"tags": [
"legend",
"first computer programmer"
],
"links": {
"entities": ["7", "12", "83"],
"media": ["21_email", "21_sms"],
"notification_rules": ["30fd36ae-3922-4957-ae3e-c8f6dd27e543"]
}
},
{
"id": "22",
"first_name": "Charles",
"last_name": "Babbage",
"email": "babbage@example.com",
"timezone": "UTC",
"tags": [
"grump"
],
"links": {
"entities": [],
"media": ["22_email", "22_sms"],
"notification_rules": ["bfd8be61-3d80-4b95-94df-6e77183ce4e3"]
}
}
]
}
HTTP Request
GET /contacts
or
GET /contacts/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Update contacts
Update one or more attributes for one or more contact resources.
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/contacts/0/first_name",
"value" : "John"},
{"op" : "replace",
"path" : "/contacts/0/last_name",
"value" : 'Smith'}
]' \
'http://localhost:3081/contacts/23'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_contacts(
23,
:first_name => 'John',
:last_name => 'Smith'
)
HTTP Request
PATCH /contacts/ID[,ID,ID...]
Query Parameters
Parameters sent for contact updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | one of replace (for attributes), add or remove (for linked objects) |
| path | String | “/contacts/0/ATTRIBUTE” (e.g. ‘first_name’) or “/contacts/0/links/LINKED_OBJ” (e.g. ‘media’, ‘tags’) |
| value | -> | for attributes, a value of the correct data type for that attribute; for linked objects, the String id (or name for tags) of that object |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted contact updates were made successfully. No content is returned. |
| 404 | Contact resources could not be found for one or more of the provided ids. No contact resources were altered by this request. |
| 405 | Error The submitted contact data was not sent with the JSON-Patch MIME type application/json-patch+json. |
Delete contacts
Delete one or more contacts.
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/contacts/21'
# or
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/contacts/21,22'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.delete_contacts('21')
# or
Flapjack::Diner.delete_contacts('21', '22')
HTTP Request
DELETE /contacts/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | Contact(s) were deleted |
| 404 | Contacts could not be found for one or more of the provided ids. No contacts were deleted by this request. |
Media
The Medium resource has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| type | String | email, sms, or jabber |
| address | String | |
| interval | Integer | |
| rollup_threshold | Integer |
Create media for a contact
curl -w 'response: %{http_code} \n' -X POST -H "Content-Type: application/vnd.api+json" -d \
'{
"media": [
{
"type" : "email",
"address" : "johns@example.com",
"interval" : 120,
"rollup_threshold" : 5
}
]
}' \
http://localhost:3081/contacts/5/media
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_contact_media(
'5',
{
'type' => 'email',
'address' => 'johns@example.com',
'interval' => 120,
'rollup_threshold' => 5
}
)
HTTP Request
POST /contacts/CONTACT_ID/media
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| media | Array[Medium] | An array of Medium resources to create. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 201 | The submitted media resources were created successfully. |
| 405 | Error The submitted media data was not sent with the JSONAPI MIME type application/vnd.api+json. |
| 409 | Error Media with ids matching those submitted were found. |
| 422 | Error The submitted media data did not conform to the provided specification. |
Get media
If no media ids are provided then all media resources will be returned; if media ids are provided then only the media resources matching those ids will be returned.
NB: Ids for media resources are currently represented by a String containing the id of the associated contact, an underscore and then the type of the medium in question. This is for backwards compatibility, and is due to some historical design decisions, but is likely to change when the data handling code is reworked.
curl http://localhost:3081/media
# or
curl http://localhost:3081/media/1_email
# or
curl http://localhost:3081/media/21_jabber,22_jabber
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.media
# or
Flapjack::Diner.media('1_email')
# or
Flapjack::Diner.media('21_jabber', '22_jabber')
The commands return JSON structured like this, which is broken up by Flapjack::Diner into its constituent hashes:
{
"media": [
{
"id": "21_sms",
"type": "sms",
"address": "0123456789",
"interval": 300,
"rollup_threshold": 5,
"links": {
"contacts": ["21"]
}
},
{
"id": "22_email",
"type": "email",
"address": "abcde@example.com",
"interval": 180,
"rollup_threshold": 4,
"links": {
"contacts": ["22"]
}
}
]
}
HTTP Request
GET /media
or
GET /media/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Update media
Update one or more attributes for one or more media resources.
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/media/0/address",
"value" : "0123456789"},
{"op" : "replace",
"path" : "/media/0/interval",
"value" : 10}
]' \
'http://localhost:3081/media/21_sms'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_media(
'21_sms',
:address => '0123456789',
:interval => 10
)
HTTP Request
PATCH /media/ID[,ID,ID...]
Query Parameters
Parameters sent for medium updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | may only be replace |
| path | String | “/media/0/ATTRIBUTE” (e.g. ‘address’) |
| value | -> | a value of the correct data type for the attribute in the path |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted medium updates were made successfully. No content is returned. |
| 404 | Media resources could not be found for one or more of the provided ids. No media resources were altered by this request. |
| 405 | Error The submitted media data was not sent with the JSON-Patch MIME type application/json-patch+json. |
Delete media
Delete one or more media resources.
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/media/11_email'
# or
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/media/31_jabber,32_jabber'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.delete_media('11_email')
# or
Flapjack::Diner.delete_media('31_jabber', '32_jabber')
HTTP Request
DELETE /media/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The medium/media resources were deleted |
| 404 | Media resources could not be found for one or more of the provided ids. No media resources were deleted by this request. |
PagerDuty credentials
The PagerDuty resource has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| service_key | String | A PagerDuty service key. |
| subdomain | String | A PagerDuty account subdomain. |
| token | String | A PagerDuty API key. |
| username | String | Deprecated. A PagerDuty username. |
| password | String | Deprecated. The PagerDuty user’s password. |
Create PagerDuty credentials for a contact
curl -w 'response: %{http_code} \n' -X POST -H "Content-Type: application/vnd.api+json" -d \
'{
"pagerduty_credentials": [
{
"service_key" : "567890123456789012345678",
"subdomain" : "eggs",
"token" : "AnX4yLUtXkSBxjza7qvv"
}
]
}' \
http://localhost:3081/contacts/5/pagerduty_credentials
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_contact_pagerduty_credentials(
'5',
{
service_key: '567890123456789012345678',
subdomain: 'eggs',
token: 'AnX4yLUtXkSBxjza7qvv'
}
)
HTTP Request
POST /contacts/CONTACT_ID/pagerduty_credentials
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| pagerduty_credentials | Array[PagerDuty] | An array of PagerDuty resources to create. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 201 | The submitted PagerDuty credentials resources were created successfully. |
| 405 | Error The submitted PagerDuty credentials data was not sent with the JSONAPI MIME type application/vnd.api+json. |
| 422 | Error The submitted PagerDuty credentials data did not conform to the provided specification. |
Get PagerDuty credentials
If no contact ids are provided then all PagerDuty credentials resources will be returned; if contact ids are provided then only the PagerDuty credentials resources matching those ids will be returned.
curl http://localhost:3081/pagerduty_credentials
# or
curl http://localhost:3081/pagerduty_credentials/1
# or
curl http://localhost:3081/pagerduty_credentials/21,22
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.pagerduty_credentials
# or
Flapjack::Diner.pagerduty_credentials('1')
# or
Flapjack::Diner.pagerduty_credentials('21', '22')
The commands return JSON structured like this, which is broken up by Flapjack::Diner into its constituent hashes:
{
"pagerduty_credentials": [
{
"service_key" : "567890123456789012345678",
"subdomain" : "eggs",
"token" : "AnX4yLUtXkSBxjza7qvv",
"username" : "",
"password" : "",
"links": {
"contacts": ["21"]
}
},
{
"service_key" : "456789012345678901234567",
"subdomain" : "spam",
"token" : "SHcYRxjpupbVJMqVhoUs",
"username" : "",
"password" : "",
"links": {
"contacts": ["22"]
}
}
]
}
HTTP Request
GET /pagerduty_credentials
or
GET /pagerduty_credentials/CONTACT_ID[,CONTACT_ID,CONTACT_ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Update PagerDuty credentials
Update one or more attributes for one or more PagerDuty credentials resources.
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/pagerduty_credentials/0/service_key",
"value" : "f709af238cff46ff87a6da34cd51becb"},
{"op" : "replace",
"path" : "/pagerduty_credentials/0/token",
"value" : "ccihxyKqkAk7GnHa6LDC"}
]' \
'http://localhost:3081/pagerduty_credentials/21s'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_pagerduty_credentials(
'21',
service_key: 'f709af238cff46ff87a6da34cd51becb',
token: 'ccihxyKqkAk7GnHa6LDC'
)
HTTP Request
PATCH /pagerduty_credentials/CONTACT_ID[,CONTACT_ID,CONTACT_ID...]
Query Parameters
Parameters sent for PagerDuty credentials updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | may only be replace |
| path | String | “/pagerduty_credentials/0/ATTRIBUTE” (e.g. ‘username’) |
| value | -> | a value of the correct data type for the attribute in the path |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted PagerDuty credentials updates were made successfully. No content is returned. |
| 404 | PagerDuty credentials resources could not be found for one or more of the provided contact ids. No PagerDuty credentials resources were altered by this request. |
| 405 | Error The submitted PagerDuty credentials data was not sent with the JSON-Patch MIME type application/json-patch+json. |
Delete PagerDuty credentials
Delete one or more PagerDuty credentials resources.
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/pagerduty_credentials/11'
# or
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/pagerduty_credentials/31,32'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.delete_pagerduty_credentials('11')
# or
Flapjack::Diner.delete_pagerduty_credentials('31', '32')
HTTP Request
DELETE /pagerduty_credentials/CONTACT_ID[,CONTACT_ID,CONTACT_ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The PagerDuty credentials resources were deleted |
| 404 | PagerDuty credentials could not be found for one or more of the provided contact ids. No PagerDuty credentials were deleted by this request. |
Notification Rules
The Notification Rule resource has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| id | String | |
| contact_id | String | |
| entities | Array[String] | |
| regex_entities | Array[String] | |
| tags | Array[String] | |
| regex_tags | Array[String] | |
| time_restrictions | ||
| unknown_media | Array[String] | |
| warning_media | Array[String] | |
| critical_media | Array[String] | |
| unknown_blackhole | Boolean | |
| warning_blackhole | Boolean | |
| critical_blackhole | Boolean |
Create notification rules for a contact
curl -w 'response: %{http_code} \n' -X POST -H "Content-Type: application/vnd.api+json" -d \
'{
"notification_rules": [
{
"entities": [
"foo-app-01.example.com"
],
"regex_entities" : [
"^foo-\S{3}-\d{2}.example.com$"
],
"tags": [
"database",
"physical"
],
"regex_tags" : [],
"time_restrictions": [
{
"start_time": "2013-01-28 08:00:00",
"end_time": "2013-01-28 18:00:00",
"rrules": [
{
"validations": {
"day": [1,2,3,4,5]
},
"rule_type": "Weekly",
"interval": 1,
"week_start": 0
}
],
"exrules": [],
"rtimes": [],
"extimes": []
}
],
"unknown_media": [],
"warning_media": [
"email"
],
"critical_media": [
"sms",
"email"
],
"unknown_blackhole": false,
"warning_blackhole": false,
"critical_blackhole": false
}
]
}' \
http://localhost:3081/contacts/5/notification_rules
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_contact_notification_rules(
'5',
{
'entities' => [ 'foo-app-01.example.com' ],
'regex_entities' => [ '^foo-\S{3}-\d{2}.example.com$' ],
'tags' => [ 'database', 'physical' ],
'regex_tags' => nil,
'time_restrictions' => [
{
'start_time' => '2013-01-28 08:00:00',
'end_time' => '2013-01-28 18:00:00',
'rrules' => [
{
'validations' => {
'day' => [ 1, 2, 3, 4, 5 ]
},
'rule_type' => 'Weekly',
'interval' => 1,
'week_start' => 0
}
],
'exrules' => [],
'rtimes' => [],
'extimes' => []
}
],
'unknown_media' => [],
'warning_media' => [ 'email' ],
'critical_media' => [ 'sms', 'email' ],
'unknown_blackhole' => false,
'warning_blackhole' => false,
'critical_blackhole' => false
}
)
HTTP Request
POST /contacts/CONTACT_ID/notification_rules
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| notification_rules | Array[NotificationRule] | An array of NotificationRule resources to create. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 201 | The submitted notification rule resources were created successfully. |
| 405 | Error The submitted notification rule data was not sent with the JSONAPI MIME type application/vnd.api+json. |
| 409 | Error Notification rules with ids matching those submitted were found. |
| 422 | Error The submitted notification rule data did not conform to the provided specification. |
Get notification rules
curl http://localhost:3081/notification_rules
# or
curl http://localhost:3081/notification_rules/30fd36ae-3922-4957-ae3e-c8f6dd27e543
# or
curl http://localhost:3081/notification_rules/30fd36ae-3922-4957-ae3e-c8f6dd27e543,bfd8be61-3d80-4b95-94df-6e77183ce4e3
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.notification_rules
# or
Flapjack::Diner.notification_rules(
'30fd36ae-3922-4957-ae3e-c8f6dd27e543'
)
# or
Flapjack::Diner.notification_rules(
'30fd36ae-3922-4957-ae3e-c8f6dd27e543',
'bfd8be61-3d80-4b95-94df-6e77183ce4e3'
)
The commands return JSON structured like this, which is broken up by Flapjack::Diner into its constituent hashes:
{
"notification_rules": [
{
"entities": [
"foo-app-01.example.com"
],
"regex_entities" : [
"^foo-\S{3}-\d{2}.example.com$"
],
"tags": [
"database",
"physical"
],
"regex_tags" : [],
"time_restrictions": [
{
"start_time": "2013-01-28 08:00:00",
"end_time": "2013-01-28 18:00:00",
"rrules": [
{
"validations": {
"day": [1,2,3,4,5]
},
"rule_type": "Weekly",
"interval": 1,
"week_start": 0
}
],
"exrules": [],
"rtimes": [],
"extimes": []
}
],
"unknown_media": [],
"warning_media": [
"email"
],
"critical_media": [
"sms",
"email"
],
"unknown_blackhole": false,
"warning_blackhole": false,
"critical_blackhole": false,
"links": {
"contacts": ["12"]
}
}
]
}
HTTP Request
GET /notification_rules
or
GET /media/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Update notification rules
Update one or more attributes for one or more notification rules.
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/notification_rules/0/tags",
"value" : ["leased", "small"]}
]' \
'http://localhost:3081/notification_rules/a82fe0ec-1972-4c12-9732-6ebec9dcf479'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_notification_rules(
'a82fe0ec-1972-4c12-9732-6ebec9dcf479',
:tags => [ 'leased', 'small' ]
)
HTTP Request
PATCH /notification_rules/ID[,ID,ID...]
Query Parameters
Parameters sent for notification rule updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | may only be replace |
| path | String | “/notification_rules/0/ATTRIBUTE” (e.g. ‘warning_blackhole’) |
| value | -> | a value of the correct data type for the attribute in the path |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted notification rule updates were made successfully. No content is returned. |
| 404 | Notification rules could not be found for one or more of the provided ids. No notification rules were altered by this request. |
| 405 | Error The submitted notification rule data was not sent with the JSON-Patch MIME type application/json-patch+json. |
Delete notification rules
Delete one or more notification rules.
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/notification_rules/2caf75f4-0043-4884-b2e9-dfb418e275ba'
# or
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/notification_rules/2caf75f4-0043-4884-b2e9-dfb418e275ba,bd0dd8b6-2c72-49da-9b83-e0b283ec1931'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.delete_notification_rules(
'2caf75f4-0043-4884-b2e9-dfb418e275ba'
)
# or
Flapjack::Diner.delete_notification_rules(
'2caf75f4-0043-4884-b2e9-dfb418e275ba',
'bd0dd8b6-2c72-49da-9b83-e0b283ec1931'
)
HTTP Request
DELETE /notification_rules/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The notification rule(s) were deleted |
| 404 | Notification rules could not be found for one or more of the provided ids. No notification rules were deleted by this request. |
Entities
The Entity resource has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| name | String | |
| id | String | |
| tags | Array[String] | |
| contacts | Array[Contact] |
Create entities
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"entities": [
{
"id": "825",
"name": "foo.example.com",
"tags": [
"foo"
]
}
]
}' \
http://localhost:3081/entities
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_entities([
{
'id' => '825',
'name' => 'foo.example.com',
'tags' => [ 'foo' ]
}
])
HTTP Request
POST /entities
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| entities | Array[Entity] | An array of Entity resources to create. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 201 | The submitted entities were created successfully. |
| 405 | Error The submitted entity data was not sent with the JSONAPI MIME type application/vnd.api+json. |
| 409 | Error Entities with ids matching those submitted were found. |
| 422 | Error The submitted entity data did not conform to the provided specification. |
Get entities
If no entity ids are provided then all entities will be returned; if entity ids are provided then only the entities matching those ids will be returned.
curl http://localhost:3081/entities
# or
curl http://localhost:3081/entities/17
# or
curl http://localhost:3081/entities/17,25
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.entities
# or
Flapjack::Diner.entities('17')
# or
Flapjack::Diner.entities('17', '25')
The commands return JSON structured like this, which is broken up by Flapjack::Diner into its constituent hashes:
{
"entities": [
{
"id": "301",
"name": "www.example.com",
"tags": [
"production",
],
"links": {
"contacts": ["5", "87", "123"]
}
},
{
"id": "302",
"name": "www.example2.com",
"tags": [
"staging"
],
"links": {
"contacts": []
}
}
]
}
HTTP Request
GET /entities
or
GET /entities/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Update entities
Update one or more attributes for one or more entity resources.
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "add",
"path" : "/entities/0/links/contacts",
"value" : '352'},
{"op" : "remove",
"path" : "/entities/0/links/tags/database"
]' \
'http://localhost:3081/entities/157'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_entities(
[ '157' ],
:name => 'www.example_com',
:add_contact => '352'
:remove_tag => 'database'
)
HTTP Request
PATCH /entities/ID[,ID,ID...]
Query Parameters
Parameters sent for entity updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | one of replace (for attributes), add or remove (for linked objects) |
| path | String | “/entities/0/ATTRIBUTE” (e.g. ‘name’) or “/entities/0/links/LINKED_OBJ” (e.g. ‘contacts’, ‘tags’) |
| value | -> | for attributes, a value of the correct data type for that attribute; for linked objects, the String id (or name for tags) of that object |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The entities were updated successfully. |
| 404 | Error No matching entities were found. |
| 405 | Error The submitted entity data was not sent with the JSON-Patch MIME type application/json-patch+json. |
| 422 | Error The submitted entity data did not conform to the provided specification. |
Create scheduled maintenance periods on entities
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"scheduled_maintenances": [
{
"start_time" : "2014-04-09T16:03:25+09:30",
"duration" : 3600,
"summary" : "memory replacement"
}
]
}' \
http://localhost:3081/scheduled_maintenances/entities/825
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_scheduled_maintenances_entities(
'825',
:start_time => '2014-04-09T16:03:25+09:30',
:duration => 3600,
:summary => 'memory replacement'
)
HTTP Request
POST /scheduled_maintenances/entities/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
| duration | Integer | A length of time (in seconds) that the created scheduled maintenance periods should last. |
| summary | String | A summary of the reason for the maintenance period. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted scheduled maintenance periods were created successfully. |
| 403 | Error The required ‘start_time’ parameter was not sent. |
| 404 | Error No matching entities were found. |
| 405 | Error The submitted parameters were not sent with the JSONAPI MIME type application/json. |
Delete scheduled maintenance periods on entities
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/scheduled_maintenances/entities/34?start_time=2014-05-09T16:12:16+09:30'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.delete_scheduled_maintenances_entities(
34,
:end_time => '2014-05-09T16:12:16+09:30'
)
HTTP Request
DELETE /scheduled_maintenances/entities/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | Matching scheduled maintenance periods were deleted. |
| 403 | Error The required ‘start_time’ parameter was not sent. |
| 404 | Error No matching entities were found. |
Create unscheduled maintenance periods on entities
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"unscheduled_maintenances": [
{
"duration" : 3600,
"summary" : "fixing now"
}
]
}' \
http://localhost:3081/unscheduled_maintenances/entities/825
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_unscheduled_maintenances_entities(
'825',
:duration => 3600,
:summary => 'fixing now'
)
HTTP Request
POST /unscheduled_maintenances/entities/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| duration | Integer | A length of time (in seconds) that the unscheduled maintenance period(s) should last. |
| summary | String | A summary of the reason for the creation of the unscheduled maintenance period(s). |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted unscheduled maintenance periods were created successfully. |
| 404 | Error No matching entities were found. |
| 405 | Error The submitted parameters were not sent with the JSONAPI MIME type application/json. |
Update unscheduled maintenance periods on entities
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/unscheduled_maintenances/0/end_time",
"value" : "2014-04-09T16:12:16+09:30"},
]' \
'http://localhost:3081/unscheduled_maintenances/entities/34'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_unscheduled_maintenances_entities(
'34',
:end_time => '2014-04-09T16:12:16+09:30'
)
HTTP Request
PATCH /unscheduled_maintenances/entities/ID[,ID,ID...]
Query Parameters
Parameters sent for unscheduled maintenance period updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | may only be replace |
| path | String | “/unscheduled_maintenances/0/ATTRIBUTE” (e.g. ‘end_time’) |
| value | -> | a value of the correct data type for the attribute in the path |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | Matching unscheduled maintenance periods were updated successfully. No content is returned. |
| 404 | Entity resources could not be found for one or more of the provided ids. No unscheduled maintenance periods were altered by this request. |
| 405 | Error The submitted data was not sent with the JSON-Patch MIME type application/json-patch+json. |
Create test notifications on entities
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"test_notifications": [
{
"summary" : "testing, testing, 1, 2, 3"
}
]
}' \
http://localhost:3081/test_notifications/entities/825
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_test_notifications_entities(
'825',
:summary => 'testing, testing, 1, 2, 3'
)
HTTP Request
POST /test_notifications/entities/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| summary | String | A summary of the reason for the creation of the test notifications. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted test notifications were created successfully. |
| 404 | Error No matching entities were found. |
| 405 | Error The submitted parameters were not sent with the JSONAPI MIME type application/json. |
Checks
The Check resource has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| name | String | |
| id | String | |
| tags | Array[String] |
Create checks
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"checks": [
{
"entity_id": "825",
"name": "PING",
"tags": [
"foo"
]
}
]
}' \
http://localhost:3081/checks
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_checks([
{
'entity_id' => '825',
'name' => 'foo.example.com',
'tags' => [ 'foo' ]
}
])
HTTP Request
POST /checks
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| checks | Array[Check] | An array of Check resources to create. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 201 | The submitted checks were created successfully. |
| 405 | Error The submitted check data was not sent with the JSONAPI MIME type application/vnd.api+json. |
| 422 | Error The submitted check data did not conform to the provided specification. |
Get checks
If no check ids are provided then all entities will be returned; if check ids are provided then only the checks matching those ids will be returned. (Check ids are composed by joining together the check’s entity’s name, the character ‘:’ and the check’s name.)
curl http://localhost:3081/checks
# or
curl 'http://localhost:3081/checks/example.com:HOST'
# or
curl 'http://localhost:3081/checks/example.com:PING,example.com:SSH'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.checks
# or
Flapjack::Diner.checks('example.com:HOST')
# or
Flapjack::Diner.checks('example.com:PING', 'example.com:SSH')
The commands return JSON structured like this, which is broken up by Flapjack::Diner into its constituent hashes:
{
"checks": [
{
"id": "www.example.com:PING",
"name": "PING",
"entity_name": "www.example.com",
"enabled": true,
"tags": [
"production"
],
"links": {
"entities": ["57"]
}
},
{
"id": "www.example.com::SSH",
"name": "SSH",
"entity_name": "www.example.com",
"enabled": true,
"tags": [],
"links": {
"entities": ["57"]
}
}
]
}
HTTP Request
GET /checks
or
GET /checks/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Update checks
Update one or more checks.
(NB: disabled checks are re-enabled when new events are generated for them.)
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/checks/0/enabled",
"value" : false}
]' \
'http://localhost:3081/checks/www.example.com%3APING'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_checks(
'www.example.com:PING',
:enabled => false,
:add_tag => ['created_2013-14']
)
HTTP Request
PATCH /checks/ID[,ID,ID...]
Query Parameters
Parameters sent for check updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | one of replace (for attributes), add or remove (for linked objects) |
| path | String | “/checks/0/ATTRIBUTE” (e.g. ‘enabled’) or “/entities/0/links/LINKED_OBJ” (e.g. ‘tags’) |
| value | -> | for attributes, a value of the correct data type for that attribute (Boolean for enabled); for linked objects, the String id (or name for tags) of that object |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The check(s) were updated successfully. |
| 404 | Error No matching checks were found. |
| 405 | Error The submitted check data was not sent with the JSON-Patch MIME type application/json-patch+json. |
| 422 | Error The submitted check data did not conform to the provided specification. |
Create scheduled maintenance periods on checks
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"scheduled_maintenances": [
{
"start_time" : "2014-04-09T16:03:25+09:30",
"duration" : 3600,
"summary" : "memory replacement"
}
]
}' \
http://localhost:3081/scheduled_maintenances/checks/example.com:SSH
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_scheduled_maintenances_checks(
'example.com:SSH',
:start_time => '2014-04-09T16:03:25+09:30',
:duration => 3600,
:summary => 'memory replacement'
)
HTTP Request
POST /scheduled_maintenances/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
| duration | Integer | A length of time (in seconds) that the created scheduled maintenance periods should last. |
| summary | String | A summary of the reason for the maintenance period. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted scheduled maintenance periods were created successfully. |
| 403 | Error The required ‘start_time’ parameter was not sent. |
| 404 | Error No matching checks were found. |
| 405 | Error The submitted parameters were not sent with the JSONAPI MIME type application/json. |
Delete scheduled maintenance periods on checks
curl -w 'response: %{http_code} \n' -X DELETE \
'http://localhost:3081/scheduled_maintenances/checks/example.com:PING?start_time=2014-05-09T16:12:16+09:30'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.delete_scheduled_maintenances_checks(
'example.com:PING',
:end_time => '2014-05-09T16:12:16+09:30'
)
HTTP Request
DELETE /scheduled_maintenances/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | Matching unscheduled maintenance periods were deleted. |
| 403 | Error The required ‘start_time’ parameter was not sent. |
| 404 | Error No matching checks were found. |
Create unscheduled maintenance periods on checks
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"unscheduled_maintenances": [
{
"duration" : 3600,
"summary" : "fixing now"
}
]
}' \
http://localhost:3081/unscheduled_maintenances/checks/example.com:HOST
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_unscheduled_maintenances_checks(
'example.com:HOST',
:duration => 3600,
:summary => 'fixing now'
)
HTTP Request
POST /unscheduled_maintenances/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| duration | Integer | A length of time (in seconds) that the unscheduled maintenance period(s) should last. |
| summary | String | A summary of the reason for the creation of the unscheduled maintenance period(s). |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted unscheduled maintenance periods were created successfully. |
| 404 | Error No matching checks were found. |
| 405 | Error The submitted parameters were not sent with the JSONAPI MIME type application/json. |
Update unscheduled maintenance periods on checks
curl -w 'response: %{http_code} \n' -X PATCH -H "Content-Type: application/json-patch+json" -d \
'[
{"op" : "replace",
"path" : "/unscheduled_maintenances/0/end_time",
"value" : "2014-04-09T16:12:16+09:30"},
]' \
'http://localhost:3081/unscheduled_maintenances/checks/example.com:PING'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.update_unscheduled_maintenances_checks(
'example.com:PING',
:end_time => '2014-04-09T16:12:16+09:30'
)
HTTP Request
PATCH /unscheduled_maintenances/checks/ID[,ID,ID...]
Query Parameters
Parameters sent for unscheduled maintenance period updates must form a valid JSON Patch (RFC 6902) document. This is comprised of a bare JSON array of JSON-Patch operation objects, which have three members:
| Parameter | Type | Description |
|---|---|---|
| op | String | may only be replace |
| path | String | “/unscheduled_maintenances/0/ATTRIBUTE” (e.g. ‘end_time’) |
| value | -> | a value of the correct data type for the attribute in the path |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | Matching unscheduled maintenance periods were updated successfully. No content is returned. |
| 404 | Entity/check resources could not be found for one or more of the provided ids. No unscheduled maintenance periods were altered by this request. |
| 405 | Error The submitted data was not sent with the JSON-Patch MIME type application/json-patch+json. |
Create test notifications on checks
curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/vnd.api+json" -d \
'{
"test_notifications": [
{
"summary" : "testing, testing, 1, 2, 3"
}
]
}' \
http://localhost:3081/test_notifications/checks/example.com:HOST
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.create_test_notifications_checks(
'example.com:HOST',
:summary => 'testing, testing, 1, 2, 3'
)
HTTP Request
POST /test_notifications/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| summary | String | A summary of the reason for the creation of the test notifications. |
HTTP Return Codes
| Return code | Description |
|---|---|
| 204 | The submitted test notifications were created successfully. |
| 404 | Error No matching checks were found. |
| 405 | Error The submitted parameters were not sent with the JSONAPI MIME type application/json. |
Reports
Status of entities or checks
curl http://localhost:3081/status_report/entities
# or
curl http://localhost:3081/status_report/entities/76
# or
curl http://localhost:3081/status_report/entities/76,342
# or
curl http://localhost:3081/status_report/checks
# or
curl http://localhost:3081/status_report/checks/www.example.com:PING
# or
curl http://localhost:3081/status_report/checks/www.example.com:PING,www.example2.com:SSH
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.status_report_entities
# or
Flapjack::Diner.status_report_entities('76')
# or
Flapjack::Diner.status_report_entities('76', '342')
# or
Flapjack::Diner.status_report_checks
# or
Flapjack::Diner.status_report_checks(
'www.example.com:PING'
)
# or
Flapjack::Diner.status_report_checks(
'www.example.com:PING',
'www.example2.com:SSH'
)
HTTP Request
GET /status_report/entities
or
GET /status_report/entities/ID[,ID,ID...]
or
GET /status_report/checks
or
GET /status_report/checks/ID[,ID,ID...]
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Unscheduled maintenance periods of entities or checks
curl http://localhost:3081/unscheduled_maintenance_report/entities
# or
curl http://localhost:3081/unscheduled_maintenance_report/entities/76
# or
curl http://localhost:3081/unscheduled_maintenance_report/entities/76,342
# or
curl http://localhost:3081/unscheduled_maintenance_report/checks
# or
curl http://localhost:3081/unscheduled_maintenance_report/checks/www.example.com:PING
# or
curl http://localhost:3081/unscheduled_maintenance_report/checks/www.example.com:PING,www.example2.com:SSH
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.unscheduled_maintenance_report_entities
# or
Flapjack::Diner.unscheduled_maintenance_report_entities('76')
# or
Flapjack::Diner.unscheduled_maintenance_report_entities('76', '342')
# or
Flapjack::Diner.unscheduled_maintenance_report_checks
# or
Flapjack::Diner.unscheduled_maintenance_report_checks(
'www.example.com:PING'
)
# or
Flapjack::Diner.unscheduled_maintenance_report_checks(
'www.example.com:PING',
'www.example2.com:SSH'
)
HTTP Request
GET /unscheduled_maintenance_report/entities
or
GET /unscheduled_maintenance_report/entities/ID[,ID,ID...]
or
GET /unscheduled_maintenance_report/checks
or
GET /unscheduled_maintenance_report/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
| end_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Scheduled maintenance periods of entities or checks
curl http://localhost:3081/scheduled_maintenance_report/entities
# or
curl http://localhost:3081/scheduled_maintenance_report/entities/76
# or
curl http://localhost:3081/scheduled_maintenance_report/entities/76,342
# or
curl http://localhost:3081/scheduled_maintenance_report/checks
# or
curl http://localhost:3081/scheduled_maintenance_report/checks/www.example.com:PING
# or
curl http://localhost:3081/scheduled_maintenance_report/checks/www.example.com:PING,www.example2.com:SSH
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.scheduled_maintenance_report_entities
# or
Flapjack::Diner.scheduled_maintenance_report_entities('76')
# or
Flapjack::Diner.scheduled_maintenance_report_entities('76', '342')
# or
Flapjack::Diner.scheduled_maintenance_report_checks
# or
Flapjack::Diner.scheduled_maintenance_report_checks(
'www.example.com:PING'
)
# or
Flapjack::Diner.scheduled_maintenance_report_checks(
'www.example.com:PING',
'www.example2.com:SSH'
)
HTTP Request
GET /scheduled_maintenance_report/entities
or
GET /scheduled_maintenance_report/entities/ID[,ID,ID...]
or
GET /scheduled_maintenance_report/checks
or
GET /scheduled_maintenance_report/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
| end_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Outages of entities or checks
An outage on a check is a period of time for which the check was failing.
curl http://localhost:3081/outage_report/entities
# or
curl http://localhost:3081/outage_report/entities/76
# or
curl http://localhost:3081/outage_report/entities/76,342
# or
curl http://localhost:3081/outage_report/checks
# or
curl http://localhost:3081/outage_report/checks/www.example.com:PING
# or
curl http://localhost:3081/outage_report/checks/www.example.com:PING,www.example2.com:SSH
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.outage_report_entities
# or
Flapjack::Diner.outage_report_entities('76')
# or
Flapjack::Diner.outage_report_entities('76', '342')
# or
Flapjack::Diner.outage_report_checks
# or
Flapjack::Diner.outage_report_checks(
'www.example.com:PING'
)
# or
Flapjack::Diner.outage_report_checks(
'www.example.com:PING',
'www.example2.com:SSH'
)
HTTP Request
GET /outage_report/entities
or
GET /outage_report/entities/ID[,ID,ID...]
or
GET /outage_report/checks
or
GET /outage_report/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
| end_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Downtime of entities or checks
A downtime on a check is a period of time when the check is failing and there’s no scheduled maintenance.
curl http://localhost:3081/downtime_report/entities
# or
curl http://localhost:3081/downtime_report/entities/76
# or
curl http://localhost:3081/downtime_report/entities/76,342
# or
curl http://localhost:3081/downtime_report/checks
# or
curl http://localhost:3081/downtime_report/checks/www.example.com:PING
# or
curl http://localhost:3081/downtime_report/checks/www.example.com:PING,www.example2.com:SSH
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.downtime_report_entities
# or
Flapjack::Diner.downtime_report_entities('76')
# or
Flapjack::Diner.downtime_report_entities('76', '342')
# or
Flapjack::Diner.downtime_report_checks
# or
Flapjack::Diner.downtime_report_checks(
'www.example.com:PING'
)
# or
Flapjack::Diner.downtime_report_checks(
'www.example.com:PING',
'www.example2.com:SSH'
)
HTTP Request
GET /downtime_report/entities
or
GET /downtime_report/entities/ID[,ID,ID...]
or
GET /downtime_report/checks
or
GET /downtime_report/checks/ID[,ID,ID...]
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| start_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
| end_time | String | A date & time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ) |
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Metrics
These endpoints are all new in Flapjack 1.5.0 with the exception of GET /metrics which appeared a good long time ago.
Check Freshness
Returns the freshness distribution of all active checks in flapjack. This is the count of checks in defined age bands as follows:
- between 0 and 1 minutes
- between 1 and 5 minutes
- between 5 and 15 minutes
- between 15 minutes and 1 hour
- greater than 1 hour
curl http://localhost:3081/metrics/check_freshness
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.metrics_check_freshness
{
"check_freshness": {
"0": 0,
"60": 0,
"300": 0,
"900": 0,
"3600": 9
}
}
HTTP Request
GET /metrics/check_freshness
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Checks Summary
Returns some statistics about checks:
- total number of checks
- number of failing checks
curl http://localhost:3081/metrics/checks
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.metrics_checks
{
"checks": {
"all": 9,
"failing": 3
}
}
HTTP Request
GET /metrics/checks
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Entities Summary
Returns some statistics about entities:
- total number of entities
- number of entities with at least one failing check
curl http://localhost:3081/metrics/entities
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.metrics_entities
{
"entities": {
"all": 10,
"enabled": 7,
"failing": 3
}
}
HTTP Request
GET /metrics/entities
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
Events
Returns statistics about the processing of events (check execution results) received by Flapjack as follows:
The number of events processed:
- in total
- that had a failure state (eg ‘warning’, ‘critical’, ‘unknown’)
- that had an ok state
- that were action events (eg ‘acknowledgement’)
- that were discarded due to being invalid
The size (length) of the event queue. This number should often be zero otherwise Flapjack is not keeping up with the events being fed in from the check executors for processing.
curl http://localhost:3081/metrics/events
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.metrics_events
{
"events":
{
"processed": {
"all": 153,
"failure": 104,
"ok": 12,
"invalid": 29,
"action": 8
},
"queue": {
"length": 0
}
}
}
HTTP Request
GET /metrics/events
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |
All Metrics
Returns all of the above metrics in one http transaction, although the data structure is not exactly a straight composite. It also includes the PID of the API process, and the FQDN of the server hosting the Flapjack API. ¯\(ツ)/¯
Note, this endpoint was written a while back and doesn’t conform to JSONAPI. It will change in the next major release of Flapjack (2.0).
curl http://localhost:3081/metrics
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')
Flapjack::Diner.metrics
{
"checks" : {
"all" : 9,
"failing" : 3
},
"check_freshness" : {
"3600" : 9,
"60" : 0,
"900" : 0,
"0" : 0,
"300" : 0
},
"event_queue_length" : 0,
"pid" : 3908,
"entities" : {
"all" : 10,
"enabled" : 7,
"failing" : 3
},
"total_keys" : 246,
"processed_events_all_time" : {
"all_time" : {
"invalid" : 34,
"ok" : 12,
"all" : 158,
"action" : 8,
"failure" : 104
}
},
"fqdn" : "Limiting-Factor.local"
}
HTTP Request
GET /metrics
Query Parameters
None.
HTTP Return Codes
| Return code | Description |
|---|---|
| 200 | OK |