README.md in flapjack-diner-2.0.0.a4 vs README.md in flapjack-diner-2.0.0b1

- 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.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). +Please note that the following documentation refers to the `v2.0.0b1` 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: @@ -43,22 +43,22 @@ # Set HTTP read timeout to 5 minutes Flapjack::Diner.read_timeout(300) ``` -If you want the old behaviour wrt returning hashes with keys as strings (they're now symbols by default) then: +If you want the old behaviour with respect to returning hashes with keys as strings (they're now symbols by default) then: ```ruby Flapjack::Diner.return_keys_as_strings = true ``` ## Functions Options for all of **flapjack-diner**'s functions are organised as either: -* Ids &emdash; One or more String or Integer values; or -* Parameters &emdash; One or more Hashes +* Ids -- One or more String or Integer values; or +* Parameters -- One or more Hashes While these can be passed in in any order, the convention is that they will be ordered as listed above. If any operation fails (returning nil), the `Flapjack::Diner.last_error` method will return an error message regarding the failure. @@ -82,24 +82,17 @@ * <a name="contents_create_media">&nbsp;</a>[create_media](#create_media) * <a name="contents_media">&nbsp;</a>[media](#get_media) * <a name="contents_update_media">&nbsp;</a>[update_media](#update_media) * <a name="contents_delete_media">&nbsp;</a>[delete_media](#delete_media) -### <a name="contents_section_acceptors">&nbsp;</a>[Acceptors](#section_acceptors) +### <a name="contents_section_rules">&nbsp;</a>[Rules](#section_rules) -* <a name="contents_create_acceptors">&nbsp;</a>[create_acceptors](#create_acceptors) -* <a name="contents_acceptors">&nbsp;</a>[acceptors](#get_acceptors) -* <a name="contents_update_acceptors">&nbsp;</a>[update_acceptors](#update_acceptors) -* <a name="contents_delete_acceptors">&nbsp;</a>[delete_acceptors](#delete_acceptors) +* <a name="contents_create_rules">&nbsp;</a>[create_rules](#create_rules) +* <a name="contents_rules">&nbsp;</a>[rules](#get_rules) +* <a name="contents_update_rules">&nbsp;</a>[update_rules](#update_rules) +* <a name="contents_delete_rules">&nbsp;</a>[delete_rules](#delete_rules) -### <a name="contents_section_rejectors">&nbsp;</a>[Rejectors](#section_rejectors) - -* <a name="contents_create_rejectors">&nbsp;</a>[create_rejectors](#create_rejectors) -* <a name="contents_rejectors">&nbsp;</a>[rejectors](#get_rejectors) -* <a name="contents_update_rejectors">&nbsp;</a>[update_rejectors](#update_rejectors) -* <a name="contents_delete_rejectors">&nbsp;</a>[delete_rejectors](#delete_rejectors) - ### <a name="contents_section_tags">&nbsp;</a>[Tags](#section_tags) * <a name="contents_create_tags">&nbsp;</a>[create_tags](#create_tags) * <a name="contents_tags">&nbsp;</a>[tags](#get_tags) * <a name="contents_update_tags">&nbsp;</a>[update_tags](#update_tags) @@ -141,14 +134,16 @@ ``` ``` CHECK { - :id => STRING, + :id => UUID_STRING, :name => STRING, :enabled => BOOLEAN, - :tags => [TAG_NAME, ...] + :initial_failure_delay => INTEGER, + :repeat_failure_delay => INTEGER, + :tags => [UUID_STRING, ...] } ``` Returns false if creation failed, or the created object(s) if it succeeded. @@ -158,12 +153,12 @@ ### checks Return data for one, some or all checks. ```ruby -check = Flapjack::Diner.checks(CHECK_ID) -some_checks = Flapjack::Diner.checks(CHECK_ID, CHECK_ID, ...) +check = Flapjack::Diner.checks(UUID_STRING) +some_checks = Flapjack::Diner.checks(UUID_STRING, UUID_STRING, ...) first_page_of_checks = Flapjack::Diner.checks ``` [^](#contents_checks) @@ -172,19 +167,19 @@ Update data for one or more checks. ```ruby # update values for one check -Flapjack::Diner.update_checks(CHECK_ID, KEY => VALUE, ...) +Flapjack::Diner.update_checks(UUID_STRING, KEY => VALUE, ...) # update values for multiple checks -Flapjack::Diner.update_checks({CHECK_ID, KEY => VALUE, ...}, {CHECK_ID, KEY => VALUE, ...}) +Flapjack::Diner.update_checks({UUID_STRING, KEY => VALUE, ...}, {UUID_STRING, KEY => VALUE, ...}) ``` Acceptable update field keys are -`:enabled`, `:name` and `:tags` +`:enabled`, `:name`, `:initial_failure_delay`, `:repeat_failure_delay` and `:tags` Returns true if updating succeeded or false if updating failed. [^](#contents_update_checks) @@ -193,14 +188,14 @@ Delete one or more checks. ```ruby # delete one check -Flapjack::Diner.delete_checks(CHECK_ID) +Flapjack::Diner.delete_checks(UUID_STRING) # delete multiple check -Flapjack::Diner.delete_checks(CHECK_ID, CHECK_ID, ...) +Flapjack::Diner.delete_checks(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. [^](#contents_delete_checks) @@ -217,17 +212,17 @@ ```ruby Flapjack::Diner.create_contacts(CONTACT, ...) ``` -``` -CONTACT +```ruby +# CONTACT { - :id => STRING, + :id => UUID_STRING, :name => STRING, :timezone => STRING, - :tags => [TAG_NAME, ...] + :tags => [UUID_STRING, ...] } ``` Returns false if creation failed, or the created object(s) if it succeeded. @@ -237,12 +232,12 @@ #### contacts Return data for one, some or all contacts. ```ruby -contact = Flapjack::Diner.contacts(CONTACT_ID) -some_contacts = Flapjack::Diner.contacts(CONTACT_ID, CONTACT_ID, ...) +contact = Flapjack::Diner.contacts(UUID_STRING) +some_contacts = Flapjack::Diner.contacts(UUID_STRING, UUID_STRING, ...) first_page_of_contacts = Flapjack::Diner.contacts ``` [^](#contents_contacts) @@ -251,14 +246,14 @@ Update data for one or more contacts. ```ruby # update values for one contact -Flapjack::Diner.update_contacts(CONTACT_ID, KEY => VALUE, ...) +Flapjack::Diner.update_contacts(UUID_STRING, KEY => VALUE, ...) # update values for multiple contacts -Flapjack::Diner.update_contacts({CONTACT_ID, KEY => VALUE, ...}, {CONTACT_ID, KEY => VALUE, ...}) +Flapjack::Diner.update_contacts({UUID_STRING, KEY => VALUE, ...}, {UUID_STRING, KEY => VALUE, ...}) ``` Acceptable update field keys are `:name`, `:timezone` and `:tags` @@ -272,14 +267,14 @@ Delete one or more contacts. ```ruby # delete one contact -Flapjack::Diner.delete_contacts(CONTACT_ID) +Flapjack::Diner.delete_contacts(UUID_STRING) # delete multiple contacts -Flapjack::Diner.delete_contacts(CONTACT_ID, CONTACT_ID, ...) +Flapjack::Diner.delete_contacts(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. [^](#contents_delete_contacts) @@ -299,21 +294,20 @@ ``` ```ruby # MEDIUM { - :id => UUID, + :id => UUID_STRING, :transport => STRING, # required :address => STRING, # required (context depends on transport) :interval => INTEGER, # required (if transport != 'pagerduty') :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 - :acceptors => [ACCEPTOR_ID, ACCEPTOR_ID, ...], - :rejectors => [REJECTOR_ID, REJECTOR_ID, ...] + :contact => UUID_STRING, # required + :rules => [UUID_STRING, UUID_STRING, ...] } ``` Returns false if creation failed, or the created object(s) if it succeeded. @@ -323,12 +317,12 @@ #### media Return data for one, some or all notification media. ```ruby -medium = Flapjack::Diner.media(MEDIUM_ID) -some_media = Flapjack::Diner.media(MEDIUM_ID, MEDIUM_ID, ...) +medium = Flapjack::Diner.media(UUID_STRING) +some_media = Flapjack::Diner.media(UUID_STRING, UUID_STRING, ...) first_page_of_media = Flapjack::Diner.media ``` [^](#contents_media) @@ -337,19 +331,19 @@ Update data for one or more notification media. ```ruby # update values for one medium -Flapjack::Diner.update_media(MEDIUM_ID, KEY => VALUE, ...) +Flapjack::Diner.update_media(UUID_STRING, KEY => VALUE, ...) # update values for multiple media -Flapjack::Diner.update_media({MEDIUM_ID, KEY => VALUE, ...}, {MEDIUM_ID, KEY => VALUE, ...}) +Flapjack::Diner.update_media({UUID_STRING, KEY => VALUE, ...}, {UUID_STRING, KEY => VALUE, ...}) ``` Acceptable update field keys are -`:address`, `:interval`, `:rollup_threshold`, `:pagerduty_subdomain`, `:pagerduty_token`, `:pagerduty_ack_duration`, `:acceptors` and `:rejectors` +`:address`, `:interval`, `:rollup_threshold`, `:pagerduty_subdomain`, `:pagerduty_token`, `:pagerduty_ack_duration` and `:rules` Returns true if updating succeeded or false if updating failed. [^](#contents_update_media) @@ -358,194 +352,109 @@ Delete one or more notification media. ```ruby # delete one medium -Flapjack::Diner.delete_media(MEDIUM_ID) +Flapjack::Diner.delete_media(UUID_STRING) # delete multiple media -Flapjack::Diner.delete_media(MEDIUM_ID, MEDIUM_ID, ...) +Flapjack::Diner.delete_media(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. [^](#contents_delete_media) --- -<a name="section_acceptors">&nbsp;</a> -### Acceptors [^](#contents_section_acceptors) +<a name="section_rules">&nbsp;</a> +### Rules [^](#contents_section_rules) -<a name="create_acceptors">&nbsp;</a> -#### create_acceptors +<a name="create_rules">&nbsp;</a> +#### create_rules -Create one or more notification acceptors. +Create one or more notification rules. ```ruby -Flapjack::Diner.create_acceptors(ACCEPTOR, ...) +Flapjack::Diner.create_rules(RULE, ...) ``` -**FIXME** time_restrictions data structure isn't handled yet - ```ruby -# ACCEPTOR +# RULE { - :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, ...] + :id => UUID_STRING, + :name => STRING, + :enabled => BOOLEAN, + :blackhole => BOOLEAN, + :strategy => STRING, # one of ['global', 'all_tags', 'any_tag', 'no_tag'] + :conditions_list => STRING, # which conditions the rule will match; + # all if empty, or comma-separated subset + # of 'critical,warning,unknown' + :time_restriction_ical => STRING, + :contact => UUID_STRING, # required + :media => [UUID_STRING, ...] + :tags => [UUID_STRING, ...] } ``` Returns false if creation failed, or the created object(s) if it succeeded. -[^](#contents_create_acceptors) +[^](#contents_create_rules) -<a name="get_acceptors">&nbsp;</a> -#### acceptors +<a name="get_rules">&nbsp;</a> +#### rules -Return data for one, some or all notification acceptors. +Return data for one, some or all notification rules. ```ruby -acceptor = Flapjack::Diner.acceptors(ACCEPTOR_ID) -some_acceptors = Flapjack::Diner.acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...) -first_page_of_acceptors = Flapjack::Diner.acceptors +rule = Flapjack::Diner.rules(UUID_STRING) +some_rules = Flapjack::Diner.rules(UUID_STRING, UUID_STRING, ...) +first_page_of_rules = Flapjack::Diner.rules ``` -[^](#contents_acceptors) +[^](#contents_rules) -<a name="update_acceptors">&nbsp;</a> -#### update_acceptors +<a name="update_rules">&nbsp;</a> +#### update_rules -Update data for one or more notification acceptors. +Update data for one or more notification rules. ```ruby -# update values for one acceptor -Flapjack::Diner.update_acceptors(:id => ACCEPTOR_ID, KEY => VALUE, ...) +# update values for one rule +Flapjack::Diner.update_rules(:id => UUID_STRING, KEY => VALUE, ...) -# update values for multiple acceptors -Flapjack::Diner.update_acceptors({:id => ACCEPTOR_ID, KEY => VALUE, ...}, {:id => ACCEPTOR_ID, KEY => VALUE, ...}) +# update values for multiple rules +Flapjack::Diner.update_rules({:id => UUID_STRING, KEY => VALUE, ...}, {:id => UUID_STRING, KEY => VALUE, ...}) ``` Acceptable update field keys are - `:conditions_list`, `:is_blackhole`, `:media` and `:tags` + `:name`, `:enabled`, `:blackhole`, `:strategy`, `:conditions_list`, `:time_restrictiosn_ical`, `:media` and `:tags` Returns true if updating succeeded or false if updating failed. -[^](#contents_update_acceptors) +[^](#contents_update_rules) -<a name="delete_acceptors">&nbsp;</a> -#### delete_acceptors +<a name="delete_rules">&nbsp;</a> +#### delete_rules -Delete one or more notification acceptors. +Delete one or more notification rules. ```ruby -# delete one acceptor -Flapjack::Diner.delete_acceptors(ACCEPTOR_ID) +# delete one rule +Flapjack::Diner.delete_rules(UUID_STRING) -# delete multiple acceptors -Flapjack::Diner.delete_acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...) +# delete multiple rules +Flapjack::Diner.delete_rules(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. -[^](#contents_delete_acceptors) +[^](#contents_delete_rules) --- -<a name="section_rejectors">&nbsp;</a> -### Rules [^](#contents_section_rejectors) - -<a name="create_rejectors">&nbsp;</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, - :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' - :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_rejectors) - -<a name="get_rejectors">&nbsp;</a> -#### rejectors - -Return data for one, some or all notification rejectors. - -```ruby -rejector = Flapjack::Diner.rejectors(REJECTOR_ID) -some_rejectors = Flapjack::Diner.rejectors(REJECTOR_ID, REJECTOR_ID, ...) -first_page_of_rejectors = Flapjack::Diner.rejectors -``` - -[^](#contents_rejectors) - -<a name="update_rejectors">&nbsp;</a> -#### update_rejectors - -Update data for one or more notification rejectors. - -```ruby -# update values for one rejector -Flapjack::Diner.update_rejectors(:id => REJECTOR_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_rejectors) - -<a name="delete_rejectors">&nbsp;</a> -#### delete_rejectors - -Delete one or more notification rejectors. - -```ruby -# delete one rejector -Flapjack::Diner.delete_rejectors(REJECTOR_ID) - -# delete multiple rejectors -Flapjack::Diner.delete_rejectors(REJECTOR_ID, REJECTOR_ID, ...) -``` - -Returns true if deletion succeeded or false if deletion failed. - -[^](#contents_delete_rejectors) - ---- - <a name="section_tags">&nbsp;</a> ### Tags [^](#contents_section_tags) <a name="create_tags">&nbsp;</a> #### create_tags @@ -557,16 +466,15 @@ ``` ```ruby # TAG { + :id => UUID_STRING, :name => STRING, # required - :checks => [CHECK_ID, ...], - :contacts => [CONTACT_ID, ...], - :acceptors => [ACCEPTOR_ID, ...], - :rejectors => [REJECTOR_ID, ...] -} + :checks => [UUID_STRING, ...], + :contacts => [UUID_STRING, ...], + :rules => [UUID_STRING, ...] ``` Returns false if creation failed, or the created object(s) if it succeeded. [^](#contents_create_tags) @@ -575,12 +483,12 @@ #### tags Return data for one, some or all tags. ```ruby -tag = Flapjack::Diner.tags(TAG_NAME) -some_tags = Flapjack::Diner.tags(TAG_NAME, TAG_NAME, ...) +tag = Flapjack::Diner.tags(UUID_STRING) +some_tags = Flapjack::Diner.tags(UUID_STRING, UUID_STRING, ...) first_page_of_tags = Flapjack::Diner.tags ``` [^](#contents_tags) @@ -589,19 +497,19 @@ Update data for one or more tags. ```ruby # update values for one tag -Flapjack::Diner.update_tags(:id => TAG_NAME, KEY => VALUE, ...) +Flapjack::Diner.update_tags(:id => UUID_STRING, KEY => VALUE, ...) # update values for multiple tags -Flapjack::Diner.update_tags({:id => TAG_NAME, KEY => VALUE, ...}, {:id => TAG_NAME, KEY => VALUE, ...}) +Flapjack::Diner.update_tags({:id => UUID_STRING, KEY => VALUE, ...}, {:id => UUID_STRING, KEY => VALUE, ...}) ``` Acceptable update field keys are - `:checks`, `:contacts`, `:acceptors` and `:rejectors` + `:checks`, `:contacts` and `:rules` Returns true if updating succeeded or false if updating failed. [^](#contents_update_tags) @@ -610,14 +518,14 @@ Delete one or more tags. ```ruby # delete one tag -Flapjack::Diner.delete_tags(TAG_NAME) +Flapjack::Diner.delete_tags(UUID_STRING) # delete multiple tags -Flapjack::Diner.delete_tags(TAG_NAME, TAG_NAME, ...) +Flapjack::Diner.delete_tags(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. [^](#contents_delete_tags) @@ -637,16 +545,16 @@ ``` ```ruby SCHEDULED_MAINTENANCE { - :id => UUID, + :id => UUID_STRING, :start_time => DATETIME, # required :end_time => DATETIME, # required :summary => STRING, - :check => CHECK_ID, # one (and only one) of :check or :tag must be provided - :tag => TAG_NAME # :tag will create scheduled maintenance periods for all checks that this tag is associated with + :check => UUID_STRING, # one (and only one) of :check or :tag must be provided + :tag => UUID_STRING # :tag will create scheduled maintenance periods for all checks that this tag is associated with } ``` Returns false if creation failed, or the created object(s) if it succeeded. @@ -656,12 +564,12 @@ ### scheduled_maintenances Return data for one, some or all scheduled maintenance periods. ```ruby -scheduled_maintenance = Flapjack::Diner.scheduled_maintenances(SCHEDULED_MAINTENANCE_ID) -some_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances(SCHEDULED_MAINTENANCE_ID, SCHEDULED_MAINTENANCE_ID, ...) +scheduled_maintenance = Flapjack::Diner.scheduled_maintenances(UUID_STRING) +some_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances(UUID_STRING, UUID_STRING, ...) first_page_of_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances ``` [^](#contents_scheduled_maintenances) @@ -670,14 +578,14 @@ Update data for one or more scheduled maintenance periods. ```ruby # update values for one scheduled maintenance period -Flapjack::Diner.update_scheduled_maintenances(:id => SCHEDULED_MAINTENANCE_ID, KEY => VALUE, ...) +Flapjack::Diner.update_scheduled_maintenances(:id => UUID_STRING, KEY => VALUE, ...) # update values for multiple scheduled maintenance periods -Flapjack::Diner.update_scheduled_maintenances({:id => SCHEDULED_MAINTENANCE_ID, KEY => VALUE, ...}, {:id => SCHEDULED_MAINTENANCE_ID, KEY => VALUE, ...}) +Flapjack::Diner.update_scheduled_maintenances({:id => UUID_STRING, KEY => VALUE, ...}, {:id => UUID_STRING, KEY => VALUE, ...}) ``` Acceptable update field keys are `:start_time`, `:end_time` and `:summary` @@ -692,12 +600,12 @@ ### delete_scheduled_maintenances Delete one or more scheduled maintenance periods. ```ruby -Flapjack::Diner.delete_scheduled_maintenances(SCHEDULED_MAINTENANCE_ID) -Flapjack::Diner.delete_scheduled_maintenances(SCHEDULED_MAINTENANCE_ID, SCHEDULED_MAINTENANCE_ID, ...) +Flapjack::Diner.delete_scheduled_maintenances(UUID_STRING) +Flapjack::Diner.delete_scheduled_maintenances(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. **FIXME** we may make it a configuration setting as to whether scheduled maintenance periods that have already started (or finished) may be deleted @@ -708,12 +616,12 @@ ### unscheduled_maintenances Return data for one, some or all unscheduled maintenance periods. ```ruby -unscheduled_maintenance = Flapjack::Diner.unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID) -some_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID, UNSCHEDULED_MAINTENANCE_ID, ...) +unscheduled_maintenance = Flapjack::Diner.unscheduled_maintenances(UUID_STRING) +some_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances(UUID_STRING, UUID_STRING, ...) first_page_of_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances ``` [^](#contents_unscheduled_maintenances) @@ -721,14 +629,14 @@ ### update_unscheduled_maintenances Update data for one or more unscheduled maintenance periods. ```ruby -Flapjack::Diner.update_unscheduled_maintenances(:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE) +Flapjack::Diner.update_unscheduled_maintenances(:id => UUID_STRING, KEY => VALUE) -Flapjack::Diner.update_unscheduled_maintenances({:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE}, - {:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE}, ...) +Flapjack::Diner.update_unscheduled_maintenances({:id => UUID_STRING, KEY => VALUE}, + {:id => UUID_STRING, KEY => VALUE}, ...) ``` Acceptable update field keys are `:start_time`, `:end_time` and `:summary` @@ -743,12 +651,12 @@ ### delete_unscheduled_maintenances Delete one or more unscheduled maintenance periods. ```ruby -Flapjack::Diner.delete_unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID) -Flapjack::Diner.delete_unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID, UNSCHEDULED_MAINTENANCE_ID, ...) +Flapjack::Diner.delete_unscheduled_maintenances(UUID_STRING) +Flapjack::Diner.delete_unscheduled_maintenances(UUID_STRING, UUID_STRING, ...) ``` Returns true if deletion succeeded or false if deletion failed. **FIXME** we may make it a configuration setting as to whether unscheduled maintenance periods may be deleted @@ -772,12 +680,12 @@ ```ruby # ACKNOWLEDGEMENT { :summary => STRING, :duration => INTEGER, - :check => CHECK_ID, # one (and only one) of :check or :tag must be provided - :tag => TAG_NAME # :tag will acknowledge all failing checks that this tag is associated with + :check => UUID_STRING, # one (and only one) of :check or :tag must be provided + :tag => UUID_STRING # :tag will acknowledge all failing checks that this tag is associated with } ``` Returns false if creation failed, or the created object(s) if it succeeded. @@ -794,12 +702,13 @@ ```ruby # TEST_NOTIFICATION { :summary => STRING, - :check => CHECK_ID, # one (and only one) of :check or :tag must be provided - :tag => TAG_NAME # :tag will send test notifications for all checks that this tag is associated with + :condition => STRING, + :check => UUID_STRING, # one (and only one) of :check or :tag must be provided + :tag => UUID_STRING # :tag will send test notifications for all checks that this tag is associated with } ``` Returns false if creation failed, or the created object(s) if it succeeded. @@ -814,12 +723,12 @@ ### states Return data for one, some or all check states. ```ruby -states = Flapjack::Diner.states(STATE_ID) -some_states = Flapjack::Diner.states(STATE_ID, STATE_ID, ...) +states = Flapjack::Diner.states(UUID_STRING) +some_states = Flapjack::Diner.states(UUID_STRING, UUID_STRING, ...) first_page_of_states = Flapjack::Diner.states ``` [^](#contents_states) @@ -838,12 +747,12 @@ ### statistics Return data for one, some or all flapjack processor instances. ```ruby -statistics = Flapjack::Diner.statistics(STATISTICS_ID) -some_statistics = Flapjack::Diner.statistics(STATISTICS_ID, STATISTICS_ID, ...) +statistics = Flapjack::Diner.statistics(UUID_STRING) +some_statistics = Flapjack::Diner.statistics(UUID_STRING, UUID_STRING, ...) first_page_of_statistics = Flapjack::Diner.statistics ``` [^](#contents_statistics) @@ -872,31 +781,25 @@ | `.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', ...] | +| `.contacts` | 'rules' | ['rule', ...] | | `.contacts` | 'tags' | ['tag', ...] | -| `.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', ...] | +| `.media` | 'rules' | ['rule', ...] | +| `.rules` | 'contact' | 'contact' | +| `.rules` | 'media' | ['medium', ...] | +| `.rules` | 'tags' | ['tag', ...] | | `.scheduled_maintenances` | 'check' | 'check' | | `.states` | 'check' | 'check' | -| `.tags` | 'acceptors' | ['acceptor', ...] | | `.tags` | 'checks' | ['check', ...] | | `.tags` | 'contacts' | ['contact', ...] | -| `.tags` | 'rejectors' | ['acceptor', ...] | +| `.tags` | 'rules' | ['rule', ...] | | `.unscheduled_maintenances` | 'check' | 'check' | NB: these may be chained, as long as they follow the allowed paths above; e.g. ```ruby @@ -934,94 +837,71 @@ 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_rejectors(contact_id, opts = {}) +contact_link_rules(contact_id, opts = {}) contact_link_tags(contact_id, opts = {}) -medium_link_acceptors(medium_id, opts = {}) medium_link_alerting_checks(medium_id, opts = {}) medium_link_contact(medium_id, opts = {}) -medium_link_rejectors(medium_id, opts = {}) +medium_link_rules(medium_id, opts = {}) -acceptor_link_contact(acceptor_id, opts = {}) -acceptor_link_media(acceptor_id, opts = {}) -acceptor_link_tags(acceptor_id, opts = {}) +rule_link_contact(rule_id, opts = {}) +rule_link_media(rule_id, opts = {}) +rule_link_tags(rule_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_contacts(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 = {}) +tag_link_checks(tag_id, opts = {}) +tag_link_contacts(tag_id, opts = {}) +tag_link_rules(tag_id, opts = {}) +tag_link_scheduled_maintenances(tag_id, opts = {}) +tag_link_states(tag_id, opts = {}) +tag_link_unscheduled_maintenances(tag_id, opts = {}) ``` All returned results are paginated, and the [common options for GET requests](#common_options_get) apply here too. <a name="object_relationships_write">&nbsp;</a> ### Manipulating object relationships -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. +The following operations are supported; please note that some associations (e.g. associating an rule 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_check_link_tags(check_id, *tags_ids) +update_check_link_tags(check_id, *tags_ids) +delete_check_link_tags(check_id, *tags_ids) -create_contact_link_tags(contact_id, *tags_names) -update_contact_link_tags(contact_id, *tags_names) -delete_contact_link_tags(contact_id, *tags_names) +create_contact_link_tags(contact_id, *tags_ids) +update_contact_link_tags(contact_id, *tags_ids) +delete_contact_link_tags(contact_id, *tags_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_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_rejectors(medium_id, *rejectors_ids) -update_medium_link_rejectors(medium_id, *rejectors_ids) -delete_medium_link_rejectors(medium_id, *rejectors_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_acceptor_link_media(acceptor_id, *media_ids) -update_acceptor_link_media(acceptor_id, *media_ids) -delete_acceptor_link_media(acceptor_id, *media_ids) +create_rule_link_tags(rule_id, *tags_ids) +update_rule_link_tags(rule_id, *tags_ids) +delete_rule_link_tags(rule_id, *tags_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_tag_link_checks(tag_id, *checks_ids) +update_tag_link_checks(tag_id, *checks_ids) +delete_tag_link_checks(tag_id, *checks_ids) -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_tag_link_contacts(tag_id, *contacts_ids) +update_tag_link_contacts(tag_id, *contacts_ids) +delete_tag_link_contacts(tag_id, *contacts_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_contacts(tag_name, *contacts_ids) -update_tag_link_contacts(tag_name, *contacts_ids) -delete_tag_link_contacts(tag_name, *contacts_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) +create_tag_link_rules(tag_id, *rules_ids) +update_tag_link_rules(tag_id, *rules_ids) +delete_tag_link_rules(tag_id, *rules_ids) ``` <a name="object_relationships_write_create">&nbsp;</a> #### `create_{resource}_link_{related}`