flapjack-diner 1.4.0 → 2.0.0.a4

data/README.md

@@ -7,8 +7,7 @@
 
 Access the JSON API of a [Flapjack](http://flapjack.io/) system monitoring server.
 
-Note that flapjack-diner [releases](https://github.com/flapjack/flapjack-diner/releases) after [1.0.0.rc1](https://github.com/flapjack/flapjack-diner/releases/tag/v1.0.0.rc1) require the [JSONAPI](http://flapjack.io/docs/jsonapi) gateway of Flapjack to connect to. All previous releases (0.x) require the older [API](http://flapjack.io/docs/0.9/API) Flapjack gateway.
-
+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
 
@@ -54,122 +53,199 @@ Flapjack::Diner.return_keys_as_strings = true
 
 ## Functions
 
-Parameters for all of **flapjack-diner**'s functions are organised into three categories:
+Options for all of **flapjack-diner**'s functions are organised as either:
 
-* Ids -- One or more String or Integer values
-* Query parameters -- Top-level hash values
-* Payload data -- Arrays of Hashes
+* Ids &emdash; One or more String or Integer values; or
+* Parameters &emdash; 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), `Flapjack::Diner.last_error` will contain an error message regarding the failure.
+If any operation fails (returning nil), the `Flapjack::Diner.last_error` method will return an error message regarding the failure.
+
+<a name="contents_section_checks">&nbsp;</a>
+### <a name="contents_section_checks">&nbsp;</a>[Checks](#section_checks)
+
+* <a name="contents_create_checks">&nbsp;</a>[create_checks](#create_checks)
+* <a name="contents_checks">&nbsp;</a>[checks](#get_checks)
+* <a name="contents_update_checks">&nbsp;</a>[update_checks](#update_checks)
+* <a name="contents_delete_checks">&nbsp;</a>[delete_checks](#delete_checks)
+
+### <a name="contents_section_contacts">&nbsp;</a>[Contacts](#section_contacts)
+
+* <a name="contents_create_contacts">&nbsp;</a>[create_contacts](#create_contacts)
+* <a name="contents_contacts">&nbsp;</a>[contacts](#get_contacts)
+* <a name="contents_update_contacts">&nbsp;</a>[update_contacts](#update_contacts)
+* <a name="contents_delete_contacts">&nbsp;</a>[delete_contacts](#delete_contacts)
+
+### <a name="contents_section_media">&nbsp;</a>[Media](#section_media)
+
+* <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_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_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)
+* <a name="contents_delete_tags">&nbsp;</a>[delete_tags](#delete_tags)
+
+### <a name="contents_section_maintenance_periods">&nbsp;</a>[Maintenance periods](#section_maintenance_periods)
+
+* <a name="contents_create_scheduled_maintenances">&nbsp;</a>[create_scheduled_maintenances](#create_scheduled_maintenances)
+* <a name="contents_scheduled_maintenances">&nbsp;</a>[scheduled_maintenances](#get_scheduled_maintenances)
+* <a name="contents_update_scheduled_maintenances">&nbsp;</a>[update_scheduled_maintenances](#update_scheduled_maintenances)
+* <a name="contents_delete_scheduled_maintenances">&nbsp;</a>[delete_scheduled_maintenances](#delete_scheduled_maintenances)
+* <a name="contents_unscheduled_maintenances">&nbsp;</a>[unscheduled_maintenances](#get_unscheduled_maintenances)
+* <a name="contents_update_unscheduled_maintenances">&nbsp;</a>[update_unscheduled_maintenances](#update_unscheduled_maintenances)
+* <a name="contents_delete_unscheduled_maintenances">&nbsp;</a>[delete_unscheduled_maintenances](#delete_unscheduled_maintenances)
+
+### <a name="contents_section_events">&nbsp;</a>[Events](#section_events)
+
+* <a name="contents_create_acknowledgements">&nbsp;</a>[create_acknowledgements](#create_acknowledgements)
+* <a name="contents_create_test_notifications">&nbsp;</a>[create_test_notifications](#create_test_notifications)
+
+### <a name="contents_section_miscellaneous">&nbsp;</a>[Miscellaneous](#section_miscellaneous)
+
+* <a name="contents_states">&nbsp;</a>[states](#get_states)
+* <a name="contents_metrics">&nbsp;</a>[metrics](#get_metrics)
+* <a name="contents_statistics">&nbsp;</a>[statistics](#get_statistics)
+
+---
+
+<a name="section_checks">&nbsp;</a>
+### Checks [^](#contents_section_checks)
+
+<a name="create_checks">&nbsp;</a>
+### create_checks
+
+Create one or more checks.
 
-### Contacts
+```ruby
+Flapjack::Diner.create_checks(CHECK, ...)
+```
 
-* [create_contacts](#create_contacts)
-* [contacts](#contacts)
-* [update_contacts](#update_contacts)
-* [delete_contacts](#delete_contacts)
+```
+CHECK
+{
+  :id      => STRING,
+  :name    => STRING,
+  :enabled => BOOLEAN,
+  :tags    => [TAG_NAME, ...]
+}
+```
 
-### Media
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-* [create_contact_media](#create_contact_media)
-* [media](#media)
-* [update_media](#update_media)
-* [delete_media](#delete_media)
+[^](#contents_create_checks)
 
-### Pagerduty credentials
+<a name="get_checks">&nbsp;</a>
+### checks
 
-* [create_contact_pagerduty_credentials](#create_contact_pagerduty_credentials)
-* [pagerduty_credentials](#pagerduty_credentials)
-* [update_pagerduty_credentials](#update_pagerduty_credentials)
-* [delete_pagerduty_credentials](#delete_pagerduty_credentials)
+Return data for one, some or all checks.
 
-### Notification rules
+```ruby
+check = Flapjack::Diner.checks(CHECK_ID)
+some_checks = Flapjack::Diner.checks(CHECK_ID, CHECK_ID, ...)
+first_page_of_checks = Flapjack::Diner.checks
+```
 
-* [create_contact_notification_rules](#create_contact_notification_rules)
-* [notification_rules](#notification_rules)
-* [update_notification_rules](#update_notification_rules)
-* [delete_notification_rules](#delete_notification_rules)
+[^](#contents_checks)
 
-### Entities
+<a name="update_checks">&nbsp;</a>
+### update_checks
+
+Update data for one or more checks.
 
-* [create_entities](#create_entities)
-* [entities](#entities)
-* [entities_matching](#entities_matching)
-* [update_entities](#update_entities)
+```ruby
+# update values for one check
+Flapjack::Diner.update_checks(CHECK_ID, KEY => VALUE, ...)
 
-* [create_scheduled_maintenances_entities](#create_scheduled_maintenances_entities)
-* [delete_scheduled_maintenances_entities](#delete_scheduled_maintenances_entities)
+# update values for multiple checks
+Flapjack::Diner.update_checks({CHECK_ID, KEY => VALUE, ...}, {CHECK_ID, KEY => VALUE, ...})
+```
 
-* [create_unscheduled_maintenances_entities](#create_unscheduled_maintenances_entities)
-* [update_unscheduled_maintenances_entities](#update_unscheduled_maintenances_entities)
+Acceptable update field keys are
 
-* [create_test_notifications_entities](#create_test_notifications_entities)
+`:enabled`, `:name` and `:tags`
 
-### Checks
+Returns true if updating succeeded or false if updating failed.
 
-* [create_checks](#create_checks)
-* [checks](#checks)
-* [update_checks](#update_checks)
+[^](#contents_update_checks)
 
-* [create_scheduled_maintenances_checks](#create_scheduled_maintenances_checks)
-* [delete_scheduled_maintenances_checks](#delete_scheduled_maintenances_checks)
+<a name="delete_checks">&nbsp;</a>
+#### delete_checks
 
-* [create_unscheduled_maintenances_checks](#create_unscheduled_maintenances_checks)
-* [update_unscheduled_maintenances_checks](#update_unscheduled_maintenances_checks)
+Delete one or more checks.
 
-* [create_test_notifications_checks](#create_test_notifications_checks)
+```ruby
+# delete one check
+Flapjack::Diner.delete_checks(CHECK_ID)
 
-### Reports
+# delete multiple check
+Flapjack::Diner.delete_checks(CHECK_ID, CHECK_ID, ...)
+```
 
-* [status_report_entities](#status_report_entities)
-* [scheduled_maintenance_report_entities](#scheduled_maintenance_report_entities)
-* [unscheduled_maintenance_report_entities](#unscheduled_maintenance_report_entities)
-* [downtime_report_entities](#downtime_report_entities)
-* [outage_report_entities](#outage_report_entities)
+Returns true if deletion succeeded or false if deletion failed.
 
-* [status_report_checks](#status_report_checks)
-* [scheduled_maintenance_report_checks](#scheduled_maintenance_report_checks)
-* [unscheduled_maintenance_report_checks](#unscheduled_maintenance_report_checks)
-* [downtime_report_checks](#downtime_report_checks)
-* [outage_report_checks](#outage_report_checks)
+[^](#contents_delete_checks)
 
 ---
 
+<a name="section_contacts">&nbsp;</a>
+### Contacts [^](#contents_section_contacts)
+
 <a name="create_contacts">&nbsp;</a>
 #### create_contacts
 
 Create one or more contacts.
 
 ```ruby
-Flapjack::Diner.create_contacts([CONTACT, ...])
+Flapjack::Diner.create_contacts(CONTACT, ...)
 ```
 
 ```
 CONTACT
 {
   :id => STRING,
-  :first_name => STRING,
-  :last_name => STRING,
-  :email => STRING,
-  :tags => [STRING, ...]
+  :name => STRING,
+  :timezone => STRING,
+  :tags => [TAG_NAME, ...]
 }
 ```
 
-Returns an array of contact ids if creation succeeded, or false if creation failed.
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-<a name="contacts">&nbsp;</a>
+[^](#contents_create_contacts)
+
+<a name="get_contacts">&nbsp;</a>
 #### contacts
 
 Return data for one, some or all contacts.
 
 ```ruby
-contact = Flapjack::Diner.contacts(ID)
-some_contacts = Flapjack::Diner.contacts(ID1, ID2, ...)
-all_contacts = Flapjack::Diner.contacts
+contact = Flapjack::Diner.contacts(CONTACT_ID)
+some_contacts = Flapjack::Diner.contacts(CONTACT_ID, CONTACT_ID, ...)
+first_page_of_contacts = Flapjack::Diner.contacts
 ```
 
+[^](#contents_contacts)
+
 <a name="update_contacts">&nbsp;</a>
 #### update_contacts
 
@@ -177,27 +253,20 @@ Update data for one or more contacts.
 
 ```ruby
 # update values for one contact
-Flapjack::Diner.update_contacts(ID, :key => value, ...)
+Flapjack::Diner.update_contacts(CONTACT_ID, KEY => VALUE, ...)
 
 # update values for multiple contacts
-Flapjack::Diner.update_contacts(ID1, ID2, ..., :key => value, ...)
+Flapjack::Diner.update_contacts({CONTACT_ID, KEY => VALUE, ...}, {CONTACT_ID, KEY => VALUE, ...})
 ```
 
 Acceptable update field keys are
 
-`:first_name`, `:last_name`, `:email`
-
-as well as the linkage operations
-
-`:add_entity`, `:remove_entity`
-`:add_notification_rule`, `:remove_notification_rule`
-
-which take the id (for entity and notification rule) of the relevant resource as the value.
-
-(NB: `:add_medium` and `:remove_medium` are not supported in Flapjack v1.x but will be in future versions.)
+`:name`, `:timezone` and `:tags`
 
 Returns true if updating succeeded, false if updating failed.
 
+[^](#contents_update_contacts)
+
 <a name="delete_contacts">&nbsp;</a>
 #### delete_contacts
 
@@ -205,48 +274,64 @@ Delete one or more contacts.
 
 ```ruby
 # delete one contact
-Flapjack::Diner.delete_contacts(ID)
+Flapjack::Diner.delete_contacts(CONTACT_ID)
 
 # delete multiple contacts
-Flapjack::Diner.delete_contacts(ID1, ID2, ...)
+Flapjack::Diner.delete_contacts(CONTACT_ID, CONTACT_ID, ...)
 ```
 
 Returns true if deletion succeeded or false if deletion failed.
 
+[^](#contents_delete_contacts)
+
 ---
 
-<a name="create_contact_media">&nbsp;</a>
-#### create_contact_media
+<a name="section_media">&nbsp;</a>
+### Media [^](#contents_section_media)
+
+<a name="create_media">&nbsp;</a>
+#### create_media
 
 Create one or more notification media.
 
 ```ruby
-Flapjack::Diner.create_contact_media(CONTACT_ID, [MEDIUM, ...])
+Flapjack::Diner.create_media(MEDIUM, MEDIUM, ...)
 ```
 
-```
-MEDIUM
+```ruby
+# MEDIUM
 {
-  :type => STRING,
-  :address => STRING,
-  :interval => INTEGER,
-  :rollup_threshold => INTEGER
+  :id => UUID,
+  :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, ...]
 }
 ```
 
-Returns an array of media ids if creation succeeded, or false if creation failed. (Ids cannot be passed in for media records in Flapjack v1.x.)
+Returns false if creation failed, or the created object(s) if it succeeded.
+
+[^](#contents_create_media)
 
-<a name="media">&nbsp;</a>
+<a name="get_media">&nbsp;</a>
 #### media
 
-Return data for one, some or all notification media. Notification media ids are formed by compounding their linked contact's ID and their type in a string (e.g. '23_sms').
+Return data for one, some or all notification media.
 
 ```ruby
-medium = Flapjack::Diner.media(ID)
-some_media = Flapjack::Diner.media(ID1, ID2, ...)
-all_media = Flapjack::Diner.media
+medium = Flapjack::Diner.media(MEDIUM_ID)
+some_media = Flapjack::Diner.media(MEDIUM_ID, MEDIUM_ID, ...)
+first_page_of_media = Flapjack::Diner.media
 ```
 
+[^](#contents_media)
+
 <a name="update_media">&nbsp;</a>
 #### update_media
 
@@ -254,18 +339,20 @@ Update data for one or more notification media.
 
 ```ruby
 # update values for one medium
-Flapjack::Diner.update_media(ID, :key => value, ...)
+Flapjack::Diner.update_media(MEDIUM_ID, KEY => VALUE, ...)
 
 # update values for multiple media
-Flapjack::Diner.update_media(ID1, ID2, ..., :key => value, ...)
+Flapjack::Diner.update_media({MEDIUM_ID, KEY => VALUE, ...}, {MEDIUM_ID, KEY => VALUE, ...})
 ```
 
 Acceptable update field keys are
 
-`:address`, `:interval`, `:rollup_threshold`
+`: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)
+
 <a name="delete_media">&nbsp;</a>
 #### delete_media
 
@@ -273,564 +360,684 @@ Delete one or more notification media.
 
 ```ruby
 # delete one medium
-Flapjack::Diner.delete_media(ID)
+Flapjack::Diner.delete_media(MEDIUM_ID)
 
 # delete multiple media
-Flapjack::Diner.delete_media(ID1, ID2, ...)
+Flapjack::Diner.delete_media(MEDIUM_ID, MEDIUM_ID, ...)
 ```
 
 Returns true if deletion succeeded or false if deletion failed.
 
+[^](#contents_delete_media)
+
 ---
 
-<a name="create_contact_pagerduty_credentials">&nbsp;</a>
-#### create_contact_pagerduty_credentials
+<a name="section_acceptors">&nbsp;</a>
+### Acceptors [^](#contents_section_acceptors)
+
+<a name="create_acceptors">&nbsp;</a>
+#### create_acceptors
 
-Create pagerduty credentials for a contact.
+Create one or more notification acceptors.
 
 ```ruby
-Flapjack::Diner.create_contact_pagerduty_credentials(CONTACT_ID, PAGERDUTY_CREDENTIALS)
+Flapjack::Diner.create_acceptors(ACCEPTOR, ...)
 ```
 
-```
-PAGERDUTY_CREDENTIALS
+**FIXME** time_restrictions data structure isn't handled yet
+
+```ruby
+# ACCEPTOR
 {
-  :service_key => STRING,
-  :subdomain => STRING,
-  :username => STRING,
-  :password => STRING
+  :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 an array of contact ids if creation succeeded, or false if creation failed. (As contacts may only have one set of pagerduty credentials, Flapjack v1.x does not store a separate data model, thus theses objects have no separate ids.)
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-<a name="pagerduty_credentials">&nbsp;</a>
-#### pagerduty_credentials
+[^](#contents_create_acceptors)
 
-Return pagerduty credentials for a contact.
+<a name="get_acceptors">&nbsp;</a>
+#### acceptors
+
+Return data for one, some or all notification acceptors.
 
 ```ruby
-pagerduty_credentials = Flapjack::Diner.pagerduty_credentials(CONTACT_ID)
-some_pagerduty_credentials = Flapjack::Diner.pagerduty_credentials(CONTACT_ID1, CONTACT_ID2, ...)
-all_pagerduty_credentials = Flapjack::Diner.pagerduty_credentials
+acceptor = Flapjack::Diner.acceptors(ACCEPTOR_ID)
+some_acceptors = Flapjack::Diner.acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...)
+first_page_of_acceptors = Flapjack::Diner.acceptors
 ```
 
-<a name="update_pagerduty_credentials">&nbsp;</a>
-#### update_pagerduty_credentials
+[^](#contents_acceptors)
+
+<a name="update_acceptors">&nbsp;</a>
+#### update_acceptors
 
-Update pagerduty credentials for one or more contacts.
+Update data for one or more notification acceptors.
 
 ```ruby
-# update pagerduty_credentials for one contact
-Flapjack::Diner.update_pagerduty_credentials(CONTACT_ID, :key => value, ...)
+# update values for one acceptor
+Flapjack::Diner.update_acceptors(:id => ACCEPTOR_ID, KEY => VALUE, ...)
 
-# update pagerduty_credentials for multiple contacts
-Flapjack::Diner.update_pagerduty_credentials(CONTACT_ID1, CONTACT_ID2, ..., :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
 
-`:service_key`, `:subdomain`, `:username`, `:password`
+  `:conditions_list`, `:is_blackhole`, `:media` and `:tags`
 
 Returns true if updating succeeded or false if updating failed.
 
-<a name="delete_pagerduty_credentials">&nbsp;</a>
-#### delete_pagerduty_credentials
+[^](#contents_update_acceptors)
+
+<a name="delete_acceptors">&nbsp;</a>
+#### delete_acceptors
 
-Delete pagerduty credentials for one or more contacts
+Delete one or more notification acceptors.
 
 ```ruby
-# delete pagerduty_credentials for one contact
-Flapjack::Diner.delete_pagerduty_credentials(CONTACT_ID)
+# delete one acceptor
+Flapjack::Diner.delete_acceptors(ACCEPTOR_ID)
 
-# delete pagerduty_credentials for multiple contacts
-Flapjack::Diner.delete_pagerduty_credentials(CONTACT_ID1, CONTACT_ID2, ...)
+# 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="create_contact_notification_rules">&nbsp;</a>
-#### create_contact_notification_rules
+<a name="section_rejectors">&nbsp;</a>
+### Rules [^](#contents_section_rejectors)
+
+<a name="create_rejectors">&nbsp;</a>
+#### create_rejectors
 
-Create one or more notification rules.
+Create one or more notification rejectors.
 
 ```ruby
-Flapjack::Diner.create_contact_notification_rules(CONTACT_ID, [NOTIFICATION_RULE, ...])
+Flapjack::Diner.create_rejectors(REJECTOR, ...)
 ```
 
-```
-NOTIFICATION_RULE
+**FIXME** time_restrictions data structure isn't handled yet
+
+```ruby
+# REJECTOR
 {
-  :id => STRING,
-  :entities => [STRING, ...],
-  :regex_entities => [STRING, ...],
-  :tags => [STRING, ...],
-  :regex_tags => [STRING, ...],
-  :time_restrictions => TODO,
-  :unknown_media => [STRING, ...],
-  :warning_media => [STRING, ...],
-  :critical_media => [STRING, ...],
-  :unknown_blackhole => BOOLEAN,
-  :warning_blackhole => BOOLEAN,
-  :critical_blackhole => BOOLEAN
+  :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 an array of notification rule ids if creation succeeded, or false if creation failed.
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-<a name="notification_rules">&nbsp;</a>
-#### notification_rules
+[^](#contents_create_rejectors)
 
-Return data for one, some or all notification rules.
+<a name="get_rejectors">&nbsp;</a>
+#### rejectors
+
+Return data for one, some or all notification rejectors.
 
 ```ruby
-notification_rule = Flapjack::Diner.notification_rules(ID)
-some_notification_rules = Flapjack::Diner.notification_rules(ID1, ID2, ...)
-all_notification_rules = Flapjack::Diner.notification_rules
+rejector = Flapjack::Diner.rejectors(REJECTOR_ID)
+some_rejectors = Flapjack::Diner.rejectors(REJECTOR_ID, REJECTOR_ID, ...)
+first_page_of_rejectors = Flapjack::Diner.rejectors
 ```
 
-<a name="update_notification_rules">&nbsp;</a>
-#### update_notification_rules
+[^](#contents_rejectors)
+
+<a name="update_rejectors">&nbsp;</a>
+#### update_rejectors
 
-Update data for one or more notification rules.
+Update data for one or more notification rejectors.
 
 ```ruby
-# update values for one notification rule
-Flapjack::Diner.update_notification_rules(ID, :key => value, ...)
+# update values for one rejector
+Flapjack::Diner.update_rejectors(:id => REJECTOR_ID, KEY => VALUE, ...)
 
-# update values for multiple notification rules
-Flapjack::Diner.update_notification_rules(ID1, ID2, ..., :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
 
-`:entities`, `:regex_entities`, `:tags`, `:regex_tags`, `:time_restrictions`, `:unknown_media`,  `:warning_media`, `:critical_media`, `:unknown_blackhole`, `:warning_blackhole`, and `:critical_blackhole`
+  `:conditions_list`, `:is_blackhole`, `:media` and `:tags`
 
 Returns true if updating succeeded or false if updating failed.
 
-<a name="delete_notification_rules">&nbsp;</a>
-#### delete_notification_rules
+[^](#contents_update_rejectors)
+
+<a name="delete_rejectors">&nbsp;</a>
+#### delete_rejectors
 
-Delete one or more notification rules.
+Delete one or more notification rejectors.
 
 ```ruby
-# delete one medium
-Flapjack::Diner.delete_notification_rules(ID)
+# delete one rejector
+Flapjack::Diner.delete_rejectors(REJECTOR_ID)
 
-# delete multiple contacts
-Flapjack::Diner.delete_notification_rules(ID1, ID2, ...)
+# 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="create_entities">&nbsp;</a>
-### create_entities
+<a name="section_tags">&nbsp;</a>
+### Tags [^](#contents_section_tags)
 
-Create one or more entities.
+<a name="create_tags">&nbsp;</a>
+#### create_tags
+
+Create one or more tags.
 
 ```ruby
-Flapjack::Diner.create_entities([ENTITY, ...])
+Flapjack::Diner.create_tags(TAG, ...)
 ```
 
-```
-ENTITY
+```ruby
+# TAG
 {
-  :id => STRING,
-  :name => STRING,
-  :tags => [STRING, ...]
+  :name      => STRING,         # required
+  :checks    => [CHECK_ID, ...],
+  :contacts  => [CONTACT_ID, ...],
+  :acceptors => [ACCEPTOR_ID, ...],
+  :rejectors => [REJECTOR_ID, ...]
 }
 ```
 
-Returns an array of entity ids if creation succeeded, or false if creation failed.
-
-<a name="entities">&nbsp;</a>
-### entities
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-Return data for one, some or all entities.
-
-```ruby
-entity = Flapjack::Diner.entities(ID)
-some_entities = Flapjack::Diner.entities(ID1, ID2, ...)
-all_entities = Flapjack::Diner.entities
-```
+[^](#contents_create_tags)
 
-<a name="entities_matching">&nbsp;</a>
-### entities_matching
+<a name="get_tags">&nbsp;</a>
+#### tags
 
-Returns an array of entities matching a given regular expression
+Return data for one, some or all tags.
 
 ```ruby
-entities = Flapjack::Diner.entities_matching(/^db-app-01/)
+tag = Flapjack::Diner.tags(TAG_NAME)
+some_tags = Flapjack::Diner.tags(TAG_NAME, TAG_NAME, ...)
+first_page_of_tags = Flapjack::Diner.tags
 ```
 
-<a name="update_entities">&nbsp;</a>
-### update_entities
+[^](#contents_tags)
 
-Update data for one or more entities.
+<a name="update_tags">&nbsp;</a>
+#### update_tags
+
+Update data for one or more tags.
 
 ```ruby
-# update values for one entity
-Flapjack::Diner.update_entities(ID, :key => value, ...)
+# update values for one tag
+Flapjack::Diner.update_tags(:id => TAG_NAME, KEY => VALUE, ...)
 
-# update values for multiple entities
-Flapjack::Diner.update_entities(ID1, ID2, ..., :key => value, ...)
+# update values for multiple tags
+Flapjack::Diner.update_tags({:id => TAG_NAME, KEY => VALUE, ...}, {:id => TAG_NAME, KEY => VALUE, ...})
 ```
 
-There are no valid update field keys yet.
-
-The linkage operations
-
-`:add_contact` and `:remove_contact`
-`:add_tag` and `:remove_tag`
+Acceptable update field keys are
 
-take the id (for contact) or the name (for tag) of the relevant resource as the value.
+  `:checks`, `:contacts`, `:acceptors` and `:rejectors`
 
 Returns true if updating succeeded or false if updating failed.
 
+[^](#contents_update_tags)
 
-<a name="create_scheduled_maintenances_entities">&nbsp;</a>
-### create_scheduled_maintenances_entities
+<a name="delete_tags">&nbsp;</a>
+#### delete_tags
 
-Create one or more scheduled maintenance periods (`duration` seconds in length) on all checks for the provided entities.
+Delete one or more tags.
 
 ```ruby
-Flapjack::Diner.create_scheduled_maintenances_entities(ENTITY_ID(S), [SCHEDULED_MAINTENANCE, ...])
-```
+# delete one tag
+Flapjack::Diner.delete_tags(TAG_NAME)
 
-```
-SCHEDULED_MAINTENANCE
-{
-  :start_time => DATETIME,
-  :duration => INTEGER,
-  :summary => STRING
-}
+# delete multiple tags
+Flapjack::Diner.delete_tags(TAG_NAME, TAG_NAME, ...)
 ```
 
-Returns true if creation succeeded or false if creation failed.
-
-<a name="delete_scheduled_maintenances_entities">&nbsp;</a>
-### delete_scheduled_maintenances_entities
+Returns true if deletion succeeded or false if deletion failed.
 
-Delete scheduled maintenance periods starting at a specific time for checks across one or more entities.
+[^](#contents_delete_tags)
 
-```ruby
-Flapjack::Diner.delete_scheduled_maintenances_entities(ENTITY_ID(S), :start_time => DATETIME)
-```
+---
 
-Returns true if deletion succeeded or false if deletion failed. Raises an exception if the `:start_time` parameter is not supplied.
+<a name="section_maintenance_periods">&nbsp;</a>
+### Maintenance periods [^](#contents_section_maintenance_periods)
 
-<a name="create_unscheduled_maintenances_entities">&nbsp;</a>
-### create_unscheduled_maintenances_entities
+<a name="create_scheduled_maintenances">&nbsp;</a>
+### create_scheduled_maintenances
 
-Acknowledges any failing checks on the passed entities and sets up unscheduled maintenance (`duration` seconds long) on them.
+Create one or more scheduled maintenance periods (`duration` seconds in length) on one or more checks.
 
 ```ruby
-Flapjack::Diner.create_unscheduled_maintenances_entities(ENTITY_ID(S), [SCHEDULED_MAINTENANCE, ...])
+Flapjack::Diner.create_scheduled_maintenances(SCHEDULED_MAINTENANCE, ...)
 ```
 
-```
-UNSCHEDULED_MAINTENANCE
+```ruby
+SCHEDULED_MAINTENANCE
 {
-  :duration => INTEGER,
-  :summary => STRING
+  :id => UUID,
+  :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
 }
 ```
 
-Returns true if creation succeeded or false if creation failed.
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-<a name="update_unscheduled_maintenances_entities">&nbsp;</a>
-### update_unscheduled_maintenances_entities
+[^](#contents_create_scheduled_maintenances)
 
-Finalises currently existing unscheduled maintenance periods for all acknowledged checks in the provided entities. The periods end at the time provided in the `:end_time` parameter.
+<a name="get_scheduled_maintenances">&nbsp;</a>
+### scheduled_maintenances
+
+Return data for one, some or all scheduled maintenance periods.
 
 ```ruby
-Flapjack::Diner.update_unscheduled_maintenances_entities(ENTITY_ID(S), :end_time => DATETIME)
+scheduled_maintenance = Flapjack::Diner.scheduled_maintenances(SCHEDULED_MAINTENANCE_ID)
+some_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances(SCHEDULED_MAINTENANCE_ID, SCHEDULED_MAINTENANCE_ID, ...)
+first_page_of_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances
 ```
 
-Returns true if the finalisation succeeded or false if deletion failed.
+[^](#contents_scheduled_maintenances)
 
-<a name="create_test_notifications_entities">&nbsp;</a>
-### create_test_notifications_entities
+<a name="update_scheduled_maintenances">&nbsp;</a>
+### update_scheduled_maintenances
 
-Instructs Flapjack to issue test notifications on all checks for the passed entities. These notifications will be sent to contacts configured to receive notifications for those checks.
+Update data for one or more scheduled maintenance periods.
 
 ```ruby
-Flapjack::Diner.create_test_notifications_entities(ENTITY_ID(S), [TEST_NOTIFICATION, ...])
-```
+# update values for one scheduled maintenance period
+Flapjack::Diner.update_scheduled_maintenances(:id => SCHEDULED_MAINTENANCE_ID, 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, ...})
 ```
-TEST_NOTIFICATION
-{
-  :summary => STRING
-}
-```
 
-Returns true if creation succeeded or false if creation failed.
+Acceptable update field keys are
+
+  `:start_time`, `:end_time` and `:summary`
 
----
+Returns true if updating succeeded or false if updating failed.
 
-<a name="create_checks">&nbsp;</a>
-### create_checks
+**FIXME** we may make it a configuration setting as to whether times in the past may be edited
 
-Create one or more checks.
+[^](#contents_update_scheduled_maintenances)
+
+<a name="delete_scheduled_maintenances">&nbsp;</a>
+### delete_scheduled_maintenances
+
+Delete one or more scheduled maintenance periods.
 
 ```ruby
-Flapjack::Diner.create_checks([CHECK, ...])
+Flapjack::Diner.delete_scheduled_maintenances(SCHEDULED_MAINTENANCE_ID)
+Flapjack::Diner.delete_scheduled_maintenances(SCHEDULED_MAINTENANCE_ID, SCHEDULED_MAINTENANCE_ID, ...)
 ```
 
-```
-CHECK
-{
-  :entity_id => STRING,
-  :name      => STRING,
-  :tags      => [STRING, ...]
-}
-```
+Returns true if deletion succeeded or false if deletion failed.
 
-Returns an array of check ids if creation succeeded, or false if creation failed. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+**FIXME** we may make it a configuration setting as to whether scheduled maintenance periods that have already started (or finished) may be deleted
 
-<a name="checks">&nbsp;</a>
-### checks
+[^](#contents_delete_scheduled_maintenances)
 
-Return basic identity data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+<a name="get_unscheduled_maintenances">&nbsp;</a>
+### unscheduled_maintenances
+
+Return data for one, some or all unscheduled maintenance periods.
 
 ```ruby
-check = Flapjack::Diner.checks(ID)
-some_checks = Flapjack::Diner.checks(ID1, ID2, ...)
-all_checks = Flapjack::Diner.checks
+unscheduled_maintenance = Flapjack::Diner.unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID)
+some_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID, UNSCHEDULED_MAINTENANCE_ID, ...)
+first_page_of_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances
 ```
 
-<a name="checks_matching">&nbsp;</a>
-### checks_matching
+[^](#contents_unscheduled_maintenances)
+
+<a name="update_unscheduled_maintenances">&nbsp;</a>
+### update_unscheduled_maintenances
 
-Returns an array of checks matching a given regular expression
+Update data for one or more unscheduled maintenance periods.
 
 ```ruby
-entities = Flapjack::Diner.checks_matching(/^PING/)
+Flapjack::Diner.update_unscheduled_maintenances(:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE)
+
+Flapjack::Diner.update_unscheduled_maintenances({:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE},
+  {:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE}, ...)
 ```
 
-<a name="update_checks">&nbsp;</a>
-### update_checks
+Acceptable update field keys are
 
-Update data for one or more checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+  `:start_time`, `:end_time` and `:summary`
 
-```ruby
-# update values for one checks
-Flapjack::Diner.update_checks(ID, :key => value, ...)
+Returns true if updating succeeded or false if updating failed.
 
-# update values for multiple checks
-Flapjack::Diner.update_checks(ID1, ID2, ..., :key => value, ...)
-```
+**FIXME** we may make it a configuration setting as to whether times in the past may be edited
 
-Acceptable update field keys are
+[^](#contents_update_unscheduled_maintenances)
 
-`:enabled`
+<a name="delete_unscheduled_maintenances">&nbsp;</a>
+### delete_unscheduled_maintenances
 
-as well as the linkage operations
+Delete one or more unscheduled maintenance periods.
 
-`:add_tag` and `:remove_tag`
+```ruby
+Flapjack::Diner.delete_unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID)
+Flapjack::Diner.delete_unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID, UNSCHEDULED_MAINTENANCE_ID, ...)
+```
 
-which take the name of the tag as the value.
+Returns true if deletion succeeded or false if deletion failed.
 
-Returns true if updating succeeded or false if updating failed.
+**FIXME** we may make it a configuration setting as to whether unscheduled maintenance periods may be deleted
+
+[^](#contents_delete_unscheduled_maintenances)
 
 ---
 
-<a name="create_scheduled_maintenances_checks">&nbsp;</a>
-### create_scheduled_maintenances_checks
+<a name="section_events">&nbsp;</a>
+### Events [^](#contents_section_events)
+
+<a name="create_acknowledgements">&nbsp;</a>
+### create_acknowledgements
 
-Create one or more scheduled maintenance periods (`duration` seconds in length) on one or more checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+Acknowledges any failing checks from those passed and sets up unscheduled maintenance (`duration` seconds long) on them.
 
 ```ruby
-Flapjack::Diner.create_scheduled_maintenances_checks(CHECK_ID(S), [SCHEDULED_MAINTENANCE, ...])
+Flapjack::Diner.create_acknowledgements(ACKNOWLEDGEMENT, ...)
 ```
 
-```
-SCHEDULED_MAINTENANCE
+```ruby
+# ACKNOWLEDGEMENT
 {
-  :start_time => DATETIME,
+  :summary => STRING,
   :duration => INTEGER,
-  :summary => STRING
+  :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
 }
 ```
 
-Returns true if creation succeeded or false if creation failed.
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-<a name="delete_scheduled_maintenances_checks">&nbsp;</a>
-### delete_scheduled_maintenances_checks
+[^](#contents_create_acknowledgements)
 
-Delete scheduled maintenance periods starting at a specific time for one or more checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+<a name="create_test_notifications">&nbsp;</a>
+### create_test_notifications
 
-```ruby
-Flapjack::Diner.delete_scheduled_maintenances_checks(CHECK_ID(S), :start_time => DATETIME)
-```
-
-Returns true if deletion succeeded or false if deletion failed. Raises an exception if the `:start_time` parameter is not supplied.
-
-<a name="create_unscheduled_maintenances_checks">&nbsp;</a>
-### create_unscheduled_maintenances_checks
-
-Acknowledges any failing checks from those passed and sets up unscheduled maintenance (`duration` seconds long) on them. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+Instructs Flapjack to issue test notifications on the passed checks. These notifications will be sent to contacts configured to receive notifications for those checks.
 
 ```ruby
-Flapjack::Diner.create_unscheduled_maintenances_checks(CHECK_ID(S), [SCHEDULED_MAINTENANCE, ...])
+Flapjack::Diner.create_test_notifications(TEST_NOTIFICATION, ...)
 ```
 
-```
-UNSCHEDULED_MAINTENANCE
+```ruby
+# TEST_NOTIFICATION
 {
-  :duration => INTEGER,
-  :summary => STRING
+  :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
 }
 ```
 
-Returns true if creation succeeded or false if creation failed.
+Returns false if creation failed, or the created object(s) if it succeeded.
 
-<a name="update_unscheduled_maintenances_checks">&nbsp;</a>
-### update_unscheduled_maintenances_checks
+[^](#contents_create_test_notifications)
 
-Finalises currently existing unscheduled maintenance periods for acknowledged checks. The periods end at the time provided in the `:end_time` parameter. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+---
+
+<a name="section_miscellaneous">&nbsp;</a>
+### Miscellaneous [^](#contents_section_miscellaneous)
+
+<a name="get_states">&nbsp;</a>
+### states
+
+Return data for one, some or all check states.
 
 ```ruby
-Flapjack::Diner.update_unscheduled_maintenances_checks(CHECK_ID(S), :end_time => DATETIME)
+states = Flapjack::Diner.states(STATE_ID)
+some_states = Flapjack::Diner.states(STATE_ID, STATE_ID, ...)
+first_page_of_states = Flapjack::Diner.states
 ```
 
-Returns true if the finalisation succeeded or false if deletion failed.
+[^](#contents_states)
 
-<a name="create_test_notifications_checks">&nbsp;</a>
-### create_test_notifications_checks
+<a name="get_metrics">&nbsp;</a>
+### metrics
 
-Instructs Flapjack to issue test notifications on the passed checks. These notifications will be sent to contacts configured to receive notifications for those checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+Return global metric data for the flapjack instance (i.e. all components backed by the shared data store).
 
 ```ruby
-Flapjack::Diner.create_test_notifications_checks(CHECK_ID(S), [TEST_NOTIFICATION, ...])
+metrics = Flapjack::Diner.metrics
 ```
 
-```
-TEST_NOTIFICATION
-{
-  :summary => STRING
-}
+[^](#contents_metrics)
+
+<a name="get_statistics">&nbsp;</a>
+### 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, ...)
+first_page_of_statistics = Flapjack::Diner.statistics
 ```
 
-Returns true if creation succeeded or false if creation failed.
+[^](#contents_statistics)
 
 ---
 
-<a name="status_report_entities">&nbsp;</a>
-### status_report_entities
-
-Return a report on status data for checks in one, some or all entities.
+<a name="common_options_get">&nbsp;</a>
+### Common options for all GET requests
+
+| Option       |  Type                       | Description |
+|--------------|-----------------------------|-------------|
+| `:fields`    |  String or Array of Strings | Limit the fields of `:include`d records |
+| `:filter`    |  Hash                       | Resources must match query terms |
+| `:include`   |  String or Array of Strings | Full resources to return with the response |
+| `:sort`      |  String or Array of Strings | How the resources should be sorted |
+| `:page`      |  Integer, > 0               | Page number |
+| `:per_page`  |  Integer, > 0               | Number of resources per page |
+
+
+<a name="common_options_get_include">&nbsp;</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`                 | 'acceptors'                       | ['acceptor', ...]              |
+| `.contacts`                 | 'checks'                          | ['check', ...]                 |
+| `.contacts`                 | 'media'                           | ['medium', ...]                |
+| `.contacts`                 | 'rejectors'                       | ['rejector', ...]              |
+| `.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', ...]                   |
+| `.scheduled_maintenances`   | 'check'                           | 'check'                        |
+| `.states`                   | 'check'                           | 'check'                        |
+| `.tags`                     | 'acceptors'                       | ['acceptor', ...]              |
+| `.tags`                     | 'checks'                          | ['check', ...]                 |
+| `.tags`                     | 'contacts'                        | ['contact', ...]               |
+| `.tags`                     | 'rejectors'                       | ['acceptor', ...]              |
+| `.unscheduled_maintenances` | 'check'                           | 'check'                        |
+
+NB: these may be chained, as long as they follow the allowed paths above; e.g.
 
 ```ruby
-report = Flapjack::Diner.status_report_entities(ENTITY_ID)
-report_some = Flapjack::Diner.status_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
-report_all = Flapjack::Diner.status_report_entities
+Flapjack::Diner.contacts(CONTACT_ID, :include => 'media.alerting_checks')
 ```
 
-<a name="scheduled_maintenance_report_entities">&nbsp;</a>
-### scheduled_maintenance_report_entities
+The above will include both the contact's media *and* any alerting checks in extra data accessible via the `Flapjack::Diner.context` method; specifically, from the value held for`:included` key in the resulting Hash.
 
-Return a report on scheduled maintenance periods for checks in one, some or all entities.
+---
+
+<a name="object_relationships_read">&nbsp;</a>
+### Retrieving object relationships
+
+The following operations are supported: they will all return data in the format
 
 ```ruby
-report = Flapjack::Diner.scheduled_maintenance_report_entities(ENTITY_ID)
-report_some = Flapjack::Diner.scheduled_maintenance_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
-report_all = Flapjack::Diner.scheduled_maintenance_report_entities
+{:type => LINKED_TYPE, :id => UUID}
 ```
 
-<a name="unscheduled_maintenance_report_entities">&nbsp;</a>
-### unscheduled_maintenance_report_entities
-
-Return a report on unscheduled maintenance periods for checks in one, some or all entities.
+(for singular resources), or
 
 ```ruby
-report = Flapjack::Diner.unscheduled_maintenance_report_entities(ENTITY_ID)
-report_some = Flapjack::Diner.unscheduled_maintenance_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
-report_all = Flapjack::Diner.unscheduled_maintenance_report_entities
+[{:type => LINKED_TYPE, :id => UUID}, {:type => LINKED_TYPE, :id => UUID}, ...]
 ```
 
-<a name="downtime_report_entities">&nbsp;</a>
-### downtime_report_entities
-
-Return a report on downtime data for checks in one, some or all entities.
+for multiple resources.
 
-```ruby
-report = Flapjack::Diner.downtime_report_entities(ENTITY_ID)
-report_some = Flapjack::Diner.downtime_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
-report_all = Flapjack::Diner.downtime_report_entities
 ```
+check_link_alerting_media(check_id, opts = {})
+check_link_contacts(check_id, opts = {})
+check_link_current_scheduled_maintenances(check_id, opts = {})
+check_link_current_state(check_id, opts = {})
+check_link_current_unscheduled_maintenance(check_id, opts = {})
+check_link_latest_notifications(check_id, opts = {})
+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 = {})
 
-<a name="outage_report_entities">&nbsp;</a>
-### outage_report_entities
+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_tags(contact_id, opts = {})
 
-Return a report on outage data for checks in one, some or all entities.
+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 = {})
 
-```ruby
-report = Flapjack::Diner.outage_report_entities(ENTITY_ID)
-report_some = Flapjack::Diner.outage_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
-report_all = Flapjack::Diner.outage_report_entities
-```
+acceptor_link_contact(acceptor_id, opts = {})
+acceptor_link_media(acceptor_id, opts = {})
+acceptor_link_tags(acceptor_id, opts = {})
 
-<a name="status_report_checks">&nbsp;</a>
-### status_report_checks
+rejector_link_contact(rejector_id, opts = {})
+rejector_link_media(rejector_id, opts = {})
+rejector_link_tags(rejector_id, opts = {})
 
-Return a report on status data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+state_link_check(state_id, opts = {})
 
-```ruby
-report = Flapjack::Diner.status_report_checks(CHECK_ID)
-report_some = Flapjack::Diner.status_report_checks(CHECK_ID1, CHECK_ID2, ...)
-report_all = Flapjack::Diner.status_report_checks
+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 = {})
 ```
 
-<a name="scheduled_maintenance_report_checks">&nbsp;</a>
-### scheduled_maintenance_report_checks
+All returned results are paginated, and the [common options for GET requests](#common_options_get) apply here too.
 
-Return a report on scheduled maintenance periods for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+<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.
 
-```ruby
-report = Flapjack::Diner.scheduled_maintenance_report_checks(CHECK_ID)
-report_some = Flapjack::Diner.scheduled_maintenance_report_checks(CHECK_ID1, CHECK_ID2, ...)
-report_all = Flapjack::Diner.scheduled_maintenance_report_checks
 ```
+create_check_link_tags(check_id, *tags_names)
+update_check_link_tags(check_id, *tags_names)
+delete_check_link_tags(check_id, *tags_names)
 
-<a name="unscheduled_maintenance_report_checks">&nbsp;</a>
-### unscheduled_maintenance_report_checks
+create_contact_link_tags(contact_id, *tags_names)
+update_contact_link_tags(contact_id, *tags_names)
+delete_contact_link_tags(contact_id, *tags_names)
 
-Return a report on unscheduled maintenance periods for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+create_medium_link_acceptors(medium_id, *acceptors_ids)
+update_medium_link_acceptors(medium_id, *acceptors_ids)
+delete_medium_link_acceptors(medium_id, *acceptors_ids)
 
-```ruby
-report = Flapjack::Diner.unscheduled_maintenance_report_checks(CHECK_ID)
-report_some = Flapjack::Diner.unscheduled_maintenance_report_checks(CHECK_ID1, CHECK_ID2, ...)
-report_all = Flapjack::Diner.unscheduled_maintenance_report_checks
-```
+create_medium_link_rejectors(medium_id, *rejectors_ids)
+update_medium_link_rejectors(medium_id, *rejectors_ids)
+delete_medium_link_rejectors(medium_id, *rejectors_ids)
 
-<a name="downtime_report_checks">&nbsp;</a>
-### downtime_report_checks
+create_acceptor_link_media(acceptor_id, *media_ids)
+update_acceptor_link_media(acceptor_id, *media_ids)
+delete_acceptor_link_media(acceptor_id, *media_ids)
 
-Return a report on downtime data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+create_acceptor_link_tags(acceptor_id, *tags_names)
+update_acceptor_link_tags(acceptor_id, *tags_names)
+delete_acceptor_link_tags(acceptor_id, *tags_names)
 
-```ruby
-report = Flapjack::Diner.downtime_report_checks(CHECK_ID)
-report_some = Flapjack::Diner.downtime_report_checks(CHECK_ID1, CHECK_ID2, ...)
-report_all = Flapjack::Diner.downtime_report_checks
-```
+create_rejector_link_media(rejector_id, *media_ids)
+update_rejector_link_media(rejector_id, *media_ids)
+delete_rejector_link_media(rejector_id, *media_ids)
 
-<a name="outage_report_checks">&nbsp;</a>
-### outage_report_checks
+create_rejector_link_tags(rejector_id, *tags_names)
+update_rejector_link_tags(rejector_id, *tags_names)
+delete_rejector_link_tags(rejector_id, *tags_names)
 
-Return a report on outage data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)
+create_tag_link_checks(tag_name, *checks_ids)
+update_tag_link_checks(tag_name, *checks_ids)
+delete_tag_link_checks(tag_name, *checks_ids)
 
-```ruby
-report = Flapjack::Diner.outage_report_checks(CHECK_ID)
-report_some = Flapjack::Diner.outage_report_checks(CHECK_ID1, CHECK_ID2, ...)
-report_all = Flapjack::Diner.outage_report_checks
+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)
 ```
 
+<a name="object_relationships_write_create">&nbsp;</a>
+#### `create_{resource}_link_{related}`
+
+Creates new links between the `resource` represented by the first argument and the `related` resources represented by the rest of the arguments. At least one `related` resource identifier must be provided. If the `related` resource is already linked, it is skipped.
+
+<a name="object_relationships_write_update">&nbsp;</a>
+#### `update_{resource}_link_{related}`
+
+Replace all current links between the `resource` represented by the first argument with the `related` resources represented by the rest of the arguments. If there are no further arguments, removes all current links of that type for the `resource`, otherwise removes any not present in the passed `related` resources and adds any that are passed but not already present.
+
+<a name="object_relationships_write_delete">&nbsp;</a>
+#### `delete_{resource}_link_{related}`
+
+Remove the link between the `resource` represented by the first argument, and the `related` resources represented by the rest of the arguments. If there is no link for a related resource, deletion is skipped for that linkage.
+
 ---
 
 ## Contributing
@@ -839,4 +1046,4 @@ report_all = Flapjack::Diner.outage_report_checks
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Create a new Pull Request