NAV
shell ruby
This is documentation for Flapjack version 0.9: If you're looking for version 1.0 documentation, click here.

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
email 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’)
value -> for attributes, a value of the correct data type for that attribute; for linked objects, the String id 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
subdomain String
username String
password String

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",
        "username" : "flapjack",
        "password" : "tomato"
      }
    ]
  }' \
 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',
    'username'    => 'flapjack',
    'password'    => 'tomato'
  }
)

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",
      "username" : "flapjack",
      "password" : "tomato",
      "links": {
        "contacts": ["21"]
      }
    },
    {
      "service_key" : "456789012345678901234567",
      "subdomain" : "spam",
      "username" : "waffle",
      "password" : "eggplant",
      "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/username",
   "value" : "genius"},
  {"op"    : "replace",
   "path"  : "/pagerduty_credentials/0/password",
   "value" : "ideas"}
]' \
 'http://localhost:3081/pagerduty_credentials/21s'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')

Flapjack::Diner.update_pagerduty_credentials(
  '21',
  :username => 'genius',
  :password => 'ideas'
)

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.

NB: The entity name cannot be changed in Flapjack v1.x due to limitations in the underlying data storage model. This will be addressed in future Flapjack releases.

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'}
]' \
 'http://localhost:3081/entities/157'
require 'flapjack-diner'
Flapjack::Diner.base_uri('localhost:3081')

Flapjack::Diner.update_entities(
  [ '157' ],
  :name         => 'www.example_com',
  :add_contacts => [ '352' ]
)

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’)
value -> for attributes, a value of the correct data type for that attribute; for linked objects, the String id 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

Disable a check

Disable a check (by setting its enabled attribute to false). This is currently the only supported check property for updates via the JSONAPI, due to limitations in the underlying data storage model. This will be addressed in future Flapjack releases.

(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
)

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 “replace”
path String “/checks/0/enabled”
value Boolean true or false

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