README.md in flapjack-diner-2.0.0.pre.alpha.2 vs README.md in flapjack-diner-2.0.0.pre.alpha.3
- old
+ new
@@ -5,11 +5,11 @@
[id_travis_link]: https://travis-ci.org/flapjack/flapjack-diner
[id_travis_img]: https://travis-ci.org/flapjack/flapjack-diner.png
Access the JSON API of a [Flapjack](http://flapjack.io/) system monitoring server.
-Please note that the following documentation refers to the `v2.0.0-alpha.1` pre-release of this gem. You may instead be looking for [documentation for the latest stable version](https://github.com/flapjack/flapjack-diner/blob/maint/1.x/README.md).
+Please note that the following documentation refers to the `v2.0.0-alpha.3` pre-release of this gem. You may instead be looking for [documentation for the latest stable version](https://github.com/flapjack/flapjack-diner/blob/maint/1.x/README.md).
## Installation
Add this line to your application's Gemfile:
@@ -82,17 +82,24 @@
* <a name="contents_create_media"> </a>[create_media](#create_media)
* <a name="contents_media"> </a>[media](#get_media)
* <a name="contents_update_media"> </a>[update_media](#update_media)
* <a name="contents_delete_media"> </a>[delete_media](#delete_media)
-### <a name="contents_section_rules"> </a>[Rules](#section_rules)
+### <a name="contents_section_acceptors"> </a>[Acceptors](#section_acceptors)
-* <a name="contents_create_rules"> </a>[create_rules](#create_rules)
-* <a name="contents_rules"> </a>[rules](#get_rules)
-* <a name="contents_update_rules"> </a>[update_rules](#update_rules)
-* <a name="contents_delete_rules"> </a>[delete_rules](#delete_rules)
+* <a name="contents_create_acceptors"> </a>[create_acceptors](#create_acceptors)
+* <a name="contents_acceptors"> </a>[acceptors](#get_acceptors)
+* <a name="contents_update_acceptors"> </a>[update_acceptors](#update_acceptors)
+* <a name="contents_delete_acceptors"> </a>[delete_acceptors](#delete_acceptors)
+### <a name="contents_section_rejectors"> </a>[Rejectors](#section_rejectors)
+
+* <a name="contents_create_rejectors"> </a>[create_rejectors](#create_rejectors)
+* <a name="contents_rejectors"> </a>[rejectors](#get_rejectors)
+* <a name="contents_update_rejectors"> </a>[update_rejectors](#update_rejectors)
+* <a name="contents_delete_rejectors"> </a>[delete_rejectors](#delete_rejectors)
+
### <a name="contents_section_tags"> </a>[Tags](#section_tags)
* <a name="contents_create_tags"> </a>[create_tags](#create_tags)
* <a name="contents_tags"> </a>[tags](#get_tags)
* <a name="contents_update_tags"> </a>[update_tags](#update_tags)
@@ -301,11 +308,12 @@
:rollup_threshold => INTEGER, # required (if transport != 'pagerduty')
:pagerduty_subdomain => STRING, # required (if transport == 'pagerduty')
:pagerduty_token => STRING, # required (if transport == 'pagerduty')
:pagerduty_ack_duration => INTEGER, # required (if transport == 'pagerduty')
:contact => CONTACT_ID, # required
- :rules => [RULE_ID, RULE_ID, ...]
+ :acceptors => [ACCEPTOR_ID, ACCEPTOR_ID, ...],
+ :rejectors => [REJECTOR_ID, REJECTOR_ID, ...]
}
```
Returns false if creation failed, or the created object(s) if it succeeded.
@@ -337,11 +345,11 @@
Flapjack::Diner.update_media({MEDIUM_ID, KEY => VALUE, ...}, {MEDIUM_ID, KEY => VALUE, ...})
```
Acceptable update field keys are
-`:address`, `:interval`, `:rollup_threshold`, `:pagerduty_subdomain`, `:pagerduty_token`, `:pagerduty_ack_duration` and `:rules`
+`:address`, `:interval`, `:rollup_threshold`, `:pagerduty_subdomain`, `:pagerduty_token`, `:pagerduty_ack_duration`, `:acceptors` and `:rejectors`
Returns true if updating succeeded or false if updating failed.
[^](#contents_update_media)
@@ -362,95 +370,179 @@
[^](#contents_delete_media)
---
-<a name="section_rules"> </a>
-### Rules [^](#contents_section_rules)
+<a name="section_acceptors"> </a>
+### Acceptors [^](#contents_section_acceptors)
-<a name="create_rules"> </a>
-#### create_rules
+<a name="create_acceptors"> </a>
+#### create_acceptors
-Create one or more notification rules.
+Create one or more notification acceptors.
```ruby
-Flapjack::Diner.create_rules(RULE, ...)
+Flapjack::Diner.create_acceptors(ACCEPTOR, ...)
```
**FIXME** time_restrictions data structure isn't handled yet
-**FIXME** should empty `conditions_list` implicitly specify blackhole -- thus
-remove the `is_blackhole` boolean?
+```ruby
+# ACCEPTOR
+{
+ :id => UUID_STRING,
+ :name => STRING,
+ :all => BOOLEAN, # apply to all checks, ignore tag linkages
+ :conditions_list => STRING, # which conditions the acceptor will match;
+ # all if empty, or comma-separated subset
+ # of 'critical,warning,unknown'
+ :contact => CONTACT_ID, # required
+ :media => [MEDIUM_ID, ...]
+ :tags => [TAG_NAME, ...]
+}
+```
+Returns false if creation failed, or the created object(s) if it succeeded.
+
+[^](#contents_create_acceptors)
+
+<a name="get_acceptors"> </a>
+#### acceptors
+
+Return data for one, some or all notification acceptors.
+
```ruby
-# RULE
+acceptor = Flapjack::Diner.acceptors(ACCEPTOR_ID)
+some_acceptors = Flapjack::Diner.acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...)
+first_page_of_acceptors = Flapjack::Diner.acceptors
+```
+
+[^](#contents_acceptors)
+
+<a name="update_acceptors"> </a>
+#### update_acceptors
+
+Update data for one or more notification acceptors.
+
+```ruby
+# update values for one acceptor
+Flapjack::Diner.update_acceptors(:id => ACCEPTOR_ID, KEY => VALUE, ...)
+
+# update values for multiple acceptors
+Flapjack::Diner.update_acceptors({:id => ACCEPTOR_ID, KEY => VALUE, ...}, {:id => ACCEPTOR_ID, KEY => VALUE, ...})
+```
+
+Acceptable update field keys are
+
+ `:conditions_list`, `:is_blackhole`, `:media` and `:tags`
+
+Returns true if updating succeeded or false if updating failed.
+
+[^](#contents_update_acceptors)
+
+<a name="delete_acceptors"> </a>
+#### delete_acceptors
+
+Delete one or more notification acceptors.
+
+```ruby
+# delete one acceptor
+Flapjack::Diner.delete_acceptors(ACCEPTOR_ID)
+
+# delete multiple acceptors
+Flapjack::Diner.delete_acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...)
+```
+
+Returns true if deletion succeeded or false if deletion failed.
+
+[^](#contents_delete_acceptors)
+
+---
+
+<a name="section_rejectors"> </a>
+### Rules [^](#contents_section_rejectors)
+
+<a name="create_rejectors"> </a>
+#### create_rejectors
+
+Create one or more notification rejectors.
+
+```ruby
+Flapjack::Diner.create_rejectors(REJECTOR, ...)
+```
+
+**FIXME** time_restrictions data structure isn't handled yet
+
+```ruby
+# REJECTOR
{
:id => UUID_STRING,
- :conditions_list => STRING, # which conditions the rule will match;
+ :name => STRING,
+ :all => BOOLEAN, # apply to all checks, ignore tag linkages
+ :conditions_list => STRING, # which conditions the rejector will match;
# all if empty, or comma-separated subset
# of 'critical,warning,unknown'
- :is_blackhole => BOOLEAN,
:contact => CONTACT_ID, # required
:media => [MEDIUM_ID, ...]
:tags => [TAG_NAME, ...]
}
```
Returns false if creation failed, or the created object(s) if it succeeded.
-[^](#contents_create_rules)
+[^](#contents_create_rejectors)
-<a name="get_rules"> </a>
-#### rules
+<a name="get_rejectors"> </a>
+#### rejectors
-Return data for one, some or all notification rules.
+Return data for one, some or all notification rejectors.
```ruby
-rule = Flapjack::Diner.rules(RULE_ID)
-some_rules = Flapjack::Diner.rules(RULE_ID, RULE_ID, ...)
-first_page_of_rules = Flapjack::Diner.rules
+rejector = Flapjack::Diner.rejectors(REJECTOR_ID)
+some_rejectors = Flapjack::Diner.rejectors(REJECTOR_ID, REJECTOR_ID, ...)
+first_page_of_rejectors = Flapjack::Diner.rejectors
```
-[^](#contents_rules)
+[^](#contents_rejectors)
-<a name="update_rules"> </a>
-#### update_rules
+<a name="update_rejectors"> </a>
+#### update_rejectors
-Update data for one or more notification rules.
+Update data for one or more notification rejectors.
```ruby
-# update values for one rule
-Flapjack::Diner.update_rules(:id => RULE_ID, KEY => VALUE, ...)
+# update values for one rejector
+Flapjack::Diner.update_rejectors(:id => REJECTOR_ID, KEY => VALUE, ...)
-# update values for multiple rules
-Flapjack::Diner.update_rules({:id => RULE_ID, KEY => VALUE, ...}, {:id => RULE_ID, KEY => VALUE, ...})
+# update values for multiple rejectors
+Flapjack::Diner.update_rejectors({:id => REJECTOR_ID, KEY => VALUE, ...}, {:id => REJECTOR_ID, KEY => VALUE, ...})
```
Acceptable update field keys are
`:conditions_list`, `:is_blackhole`, `:media` and `:tags`
Returns true if updating succeeded or false if updating failed.
-[^](#contents_update_rules)
+[^](#contents_update_rejectors)
-<a name="delete_rules"> </a>
-#### delete_rules
+<a name="delete_rejectors"> </a>
+#### delete_rejectors
-Delete one or more notification rules.
+Delete one or more notification rejectors.
```ruby
-# delete one rule
-Flapjack::Diner.delete_rules(RULE_ID)
+# delete one rejector
+Flapjack::Diner.delete_rejectors(REJECTOR_ID)
-# delete multiple rules
-Flapjack::Diner.delete_rules(RULE_ID, RULE_ID, ...)
+# delete multiple rejectors
+Flapjack::Diner.delete_rejectors(REJECTOR_ID, REJECTOR_ID, ...)
```
Returns true if deletion succeeded or false if deletion failed.
-[^](#contents_delete_rules)
+[^](#contents_delete_rejectors)
---
<a name="section_tags"> </a>
### Tags [^](#contents_section_tags)
@@ -465,13 +557,14 @@
```
```ruby
# TAG
{
- :name => STRING, # required
- :checks => [CHECK_ID, ...]
- :rules => [RULE_ID, ...]
+ :name => STRING, # required
+ :checks => [CHECK_ID, ...],
+ :acceptors => [ACCEPTOR_ID, ...],
+ :rejectors => [REJECTOR_ID, ...]
}
```
Returns false if creation failed, or the created object(s) if it succeeded.
@@ -503,11 +596,11 @@
Flapjack::Diner.update_tags({:id => TAG_NAME, KEY => VALUE, ...}, {:id => TAG_NAME, KEY => VALUE, ...})
```
Acceptable update field keys are
- `:checks` and `:rules`
+ `:checks`, `:acceptors` and `:rejectors`
Returns true if updating succeeded or false if updating failed.
[^](#contents_update_tags)
@@ -769,33 +862,39 @@
<a name="common_options_get_include"> </a>
### Associated data allowed for the include parameter
-| Method | Association | Assoc. Type |
-|-----------|--------------|-------------|
-| `.checks` | 'alerting_media' | ['medium', ...] |
-| `.checks` | 'contacts' | ['contact', ...] |
-| `.checks` | 'current_scheduled_maintenances' | ['scheduled_maintenance', ...] |
-| `.checks` | 'current_state' | 'state' |
-| `.checks` | 'current_unscheduled_maintenance' | 'unscheduled_maintenance' |
-| `.checks` | 'latest_notifications' | ['state', ...] |
-| `.checks` | 'tags' | ['tag', ...] |
-| `.contacts` | 'checks' | ['check', ...] |
-| `.contacts` | 'media' | ['medium', ...] |
-| `.contacts` | 'rules' | ['rule', ...] |
-| `.media` | 'alerting_checks' | ['check', ...] |
-| `.media` | 'contact' | 'contact' |
-| `.media` | 'rules' | ['rule', ...] |
-| `.rules` | 'contact' | 'contact' |
-| `.rules` | 'media' | ['medium', ...] |
-| `.rules` | 'tags' | ['tag', ...] |
-| `.scheduled_maintenances` | 'check' | 'check' |
-| `.states` | 'check' | 'check' |
-| `.tags` | 'checks' | ['check', ...] |
-| `.tags` | 'rules' | ['rule', ...] |
-| `.unscheduled_maintenances` | 'check' | 'check' |
+| Method | Association | Assoc. Type |
+|-----------------------------|-----------------------------------|--------------------------------|
+| `.checks` | 'alerting_media' | ['medium', ...] |
+| `.checks` | 'contacts' | ['contact', ...] |
+| `.checks` | 'current_scheduled_maintenances' | ['scheduled_maintenance', ...] |
+| `.checks` | 'current_state' | 'state' |
+| `.checks` | 'current_unscheduled_maintenance' | 'unscheduled_maintenance' |
+| `.checks` | 'latest_notifications' | ['state', ...] |
+| `.checks` | 'tags' | ['tag', ...] |
+| `.contacts` | 'acceptors' | ['acceptor', ...] |
+| `.contacts` | 'checks' | ['check', ...] |
+| `.contacts` | 'media' | ['medium', ...] |
+| `.contacts` | 'rejectors' | ['rejector', ...] |
+| `.media` | 'acceptors' | ['acceptor', ...] |
+| `.media` | 'alerting_checks' | ['check', ...] |
+| `.media` | 'contact' | 'contact' |
+| `.media` | 'rejectors' | ['rejector', ...] |
+| `.acceptors` | 'contact' | 'contact' |
+| `.acceptors` | 'media' | ['medium', ...] |
+| `.acceptors` | 'tags' | ['tag', ...] |
+| `.rejectors` | 'contact' | 'contact' |
+| `.rejectors` | 'media' | ['medium', ...] |
+| `.rejectors` | 'tags' | ['tag', ...] |
+| `.scheduled_maintenances` | 'check' | 'check' |
+| `.states` | 'check' | 'check' |
+| `.tags` | 'acceptors' | ['acceptor', ...] |
+| `.tags` | 'checks' | ['check', ...] |
+| `.tags` | 'rejectors' | ['acceptor', ...] |
+| `.unscheduled_maintenances` | 'check' | 'check' |
NB: these may be chained, as long as they follow the allowed paths above; e.g.
```ruby
Flapjack::Diner.contacts(CONTACT_ID, :include => 'media.alerting_checks')
@@ -832,58 +931,84 @@
check_link_scheduled_maintenances(check_id, opts = {})
check_link_states(check_id, opts = {})
check_link_tags(check_id, opts = {})
check_link_unscheduled_maintenances(check_id, opts = {})
+contact_link_acceptors(contact_id, opts = {})
contact_link_checks(contact_id, opts = {})
contact_link_media(contact_id, opts = {})
-contact_link_rules(contact_id, opts = {})
+contact_link_rejectors(contact_id, opts = {})
+medium_link_acceptors(medium_id, opts = {})
medium_link_alerting_checks(medium_id, opts = {})
medium_link_contact(medium_id, opts = {})
-medium_link_rules(medium_id, opts = {})
+medium_link_rejectors(medium_id, opts = {})
-rule_link_contact(rule_id, opts = {})
-rule_link_media(rule_id, opts = {})
-rule_link_tags(rule_id, opts = {})
+acceptor_link_contact(acceptor_id, opts = {})
+acceptor_link_media(acceptor_id, opts = {})
+acceptor_link_tags(acceptor_id, opts = {})
+rejector_link_contact(rejector_id, opts = {})
+rejector_link_media(rejector_id, opts = {})
+rejector_link_tags(rejector_id, opts = {})
+
state_link_check(state_id, opts = {})
+tag_link_acceptors(tag_name, opts = {})
tag_link_checks(tag_name, opts = {})
-tag_link_rules(tag_name, opts = {})
+tag_link_rejectors(tag_name, opts = {})
+tag_link_scheduled_maintenances(tag_name, opts = {})
+tag_link_states(tag_name, opts = {})
+tag_link_unscheduled_maintenances(tag_name, opts = {})
```
All returned results are paginated, and the [common options for GET requests](#common_options_get) apply here too.
<a name="object_relationships_write"> </a>
### Manipulating object relationships
-The following operations are supported; please note that some associations (e.g. associating a rule with a contact) must be made on object creation, via the secondary resource's create method, and cannot be altered later.
+The following operations are supported; please note that some associations (e.g. associating an acceptor with a contact) must be made on object creation, via the secondary resource's create method, and cannot be altered later.
```
create_check_link_tags(check_id, *tags_names)
update_check_link_tags(check_id, *tags_names)
delete_check_link_tags(check_id, *tags_names)
-create_medium_link_rules(medium_id, *rules_ids)
-update_medium_link_rules(medium_id, *rules_ids)
-delete_medium_link_rules(medium_id, *rules_ids)
+create_medium_link_acceptors(medium_id, *acceptors_ids)
+update_medium_link_acceptors(medium_id, *acceptors_ids)
+delete_medium_link_acceptors(medium_id, *acceptors_ids)
-create_rule_link_media(rule_id, *media_ids)
-update_rule_link_media(rule_id, *media_ids)
-delete_rule_link_media(rule_id, *media_ids)
+create_medium_link_rejectors(medium_id, *rejectors_ids)
+update_medium_link_rejectors(medium_id, *rejectors_ids)
+delete_medium_link_rejectors(medium_id, *rejectors_ids)
-create_rule_link_tags(rule_id, *tags_names)
-update_rule_link_tags(rule_id, *tags_names)
-delete_rule_link_tags(rule_id, *tags_names)
+create_acceptor_link_media(acceptor_id, *media_ids)
+update_acceptor_link_media(acceptor_id, *media_ids)
+delete_acceptor_link_media(acceptor_id, *media_ids)
+create_acceptor_link_tags(acceptor_id, *tags_names)
+update_acceptor_link_tags(acceptor_id, *tags_names)
+delete_acceptor_link_tags(acceptor_id, *tags_names)
+
+create_rejector_link_media(rejector_id, *media_ids)
+update_rejector_link_media(rejector_id, *media_ids)
+delete_rejector_link_media(rejector_id, *media_ids)
+
+create_rejector_link_tags(rejector_id, *tags_names)
+update_rejector_link_tags(rejector_id, *tags_names)
+delete_rejector_link_tags(rejector_id, *tags_names)
+
create_tag_link_checks(tag_name, *checks_ids)
update_tag_link_checks(tag_name, *checks_ids)
delete_tag_link_checks(tag_name, *checks_ids)
-create_tag_link_rules(tag_name, *rules_ids)
-update_tag_link_rules(tag_name, *rules_ids)
-delete_tag_link_rules(tag_name, *rules_ids)
+create_tag_link_acceptors(tag_name, *acceptors_ids)
+update_tag_link_acceptors(tag_name, *acceptors_ids)
+delete_tag_link_acceptors(tag_name, *acceptors_ids)
+
+create_tag_link_rejectors(tag_name, *rejectors_ids)
+update_tag_link_rejectors(tag_name, *rejectors_ids)
+delete_tag_link_rejectors(tag_name, *rejectors_ids)
```
<a name="object_relationships_write_create"> </a>
#### `create_{resource}_link_{related}`