README.md in flapjack-diner-1.0.0 vs README.md in flapjack-diner-1.2.0
- old
+ new
@@ -34,10 +34,20 @@
```ruby
Flapjack::Diner.logger = Logger.new('logs/flapjack_diner.log')
```
+If you want to alter timeout periods for HTTP connection open and reading responses:
+
+```ruby
+# Set HTTP connect timeout to 30 seconds
+Flapjack::Diner.open_timeout(30)
+
+# 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:
```ruby
Flapjack::Diner.return_keys_as_strings = true
```
@@ -50,11 +60,11 @@
* Query parameters -- Top-level hash values
* Payload data -- Arrays of 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, `Flapjack::Diner.last_error` will contain an error message regarding the failure.
+If any operation fails (returning nil), `Flapjack::Diner.last_error` will contain an error message regarding the failure.
### Contacts
* [create_contacts](#create_contacts)
* [contacts](#contacts)
@@ -84,10 +94,11 @@
### Entities
* [create_entities](#create_entities)
* [entities](#entities)
+* [entities_matching](#entities_matching)
* [update_entities](#update_entities)
* [create_scheduled_maintenances_entities](#create_scheduled_maintenances_entities)
* [delete_scheduled_maintenances_entities](#delete_scheduled_maintenances_entities)
@@ -96,11 +107,13 @@
* [create_test_notifications_entities](#create_test_notifications_entities)
### Checks
+* [create_checks](#create_checks)
* [checks](#checks)
+* [update_checks](#update_checks)
* [create_scheduled_maintenances_checks](#create_scheduled_maintenances_checks)
* [delete_scheduled_maintenances_checks](#delete_scheduled_maintenances_checks)
* [create_unscheduled_maintenances_checks](#create_unscheduled_maintenances_checks)
@@ -142,11 +155,11 @@
:email => STRING,
:tags => [STRING, ...]
}
```
-Returns true if creation succeeded or false if creation failed.
+Returns an array of contact ids if creation succeeded, or false if creation failed.
<a name="contacts"> </a>
#### contacts
Return data for one, some or all contacts.
@@ -170,22 +183,22 @@
Flapjack::Diner.update_contacts(ID1, ID2, ..., :key => value, ...)
```
Acceptable update field keys are
-`:first_name`, `:last_name`, `:email`, and `:tags`
+`: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 of the relevant resource as the value.
+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.0 but should be in future versions.)
+(NB: `:add_medium` and `:remove_medium` are not supported in Flapjack v1.x but will be in future versions.)
-Returns true if updating succeeded or false if updating failed.
+Returns true if updating succeeded, false if updating failed.
<a name="delete_contacts"> </a>
#### delete_contacts
Delete one or more contacts.
@@ -219,16 +232,16 @@
:interval => INTEGER,
:rollup_threshold => INTEGER
}
```
-Returns true if creation succeeded or false if creation failed.
+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.)
<a name="media"> </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. Notification media ids are formed by compounding their linked contact's ID and their type in a string (e.g. '23_sms').
```ruby
medium = Flapjack::Diner.media(ID)
some_media = Flapjack::Diner.media(ID1, ID2, ...)
all_media = Flapjack::Diner.media
@@ -269,11 +282,11 @@
Returns true if deletion succeeded or false if deletion failed.
---
<a name="create_contact_pagerduty_credentials"> </a>
-#### create_contact_media
+#### create_contact_pagerduty_credentials
Create pagerduty credentials for a contact.
```ruby
Flapjack::Diner.create_contact_pagerduty_credentials(CONTACT_ID, PAGERDUTY_CREDENTIALS)
@@ -287,11 +300,11 @@
:username => STRING,
:password => STRING
}
```
-Returns true if creation succeeded or false if creation failed.
+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.)
<a name="pagerduty_credentials"> </a>
#### pagerduty_credentials
Return pagerduty credentials for a contact.
@@ -363,11 +376,11 @@
:warning_blackhole => BOOLEAN,
:critical_blackhole => BOOLEAN
}
```
-Returns true if creation succeeded or false if creation failed.
+Returns an array of notification rule ids if creation succeeded, or false if creation failed.
<a name="notification_rules"> </a>
#### notification_rules
Return data for one, some or all notification rules.
@@ -396,11 +409,11 @@
`:entities`, `:regex_entities`, `:tags`, `:regex_tags`, `:time_restrictions`, `:unknown_media`, `:warning_media`, `:critical_media`, `:unknown_blackhole`, `:warning_blackhole`, and `:critical_blackhole`
Returns true if updating succeeded or false if updating failed.
<a name="delete_notification_rules"> </a>
-#### delete_contacts
+#### delete_notification_rules
Delete one or more notification rules.
```ruby
# delete one medium
@@ -430,11 +443,11 @@
:name => STRING,
:tags => [STRING, ...]
}
```
-Returns true if creation succeeded or false if creation failed.
+Returns an array of entity ids if creation succeeded, or false if creation failed.
<a name="entities"> </a>
### entities
Return data for one, some or all entities.
@@ -443,10 +456,19 @@
entity = Flapjack::Diner.entities(ID)
some_entities = Flapjack::Diner.entities(ID1, ID2, ...)
all_entities = Flapjack::Diner.entities
```
+<a name="entities_matching"> </a>
+### entities_matching
+
+Returns an array of entities matching a given regular expression
+
+```ruby
+entities = Flapjack::Diner.entities_matching(/^db-app-01/)
+```
+
<a name="update_entities"> </a>
### update_entities
Update data for one or more entities.
@@ -456,19 +478,18 @@
# update values for multiple entities
Flapjack::Diner.update_entities(ID1, ID2, ..., :key => value, ...)
```
-Acceptable update field keys are
+There are no valid update field keys yet.
-`:name` and `:tags`
+The linkage operations
-as well as the linkage operations
-
`:add_contact` and `:remove_contact`
+`:add_tag` and `:remove_tag`
-which take the id of the relevant contact as the value.
+take the id (for contact) or the name (for tag) of the relevant resource as the value.
Returns true if updating succeeded or false if updating failed.
<a name="create_scheduled_maintenances_entities"> </a>
@@ -550,21 +571,66 @@
Returns true if creation succeeded or false if creation failed.
---
+<a name="create_checks"> </a>
+### create_checks
+
+Create one or more checks.
+
+```ruby
+Flapjack::Diner.create_checks([CHECK, ...])
+```
+
+```
+CHECK
+{
+ :entity_id => STRING,
+ :name => STRING,
+ :tags => [STRING, ...]
+}
+```
+
+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.)
+
<a name="checks"> </a>
### checks
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.)
```ruby
-check = Flapjack::Diner.check(ID)
+check = Flapjack::Diner.checks(ID)
some_checks = Flapjack::Diner.checks(ID1, ID2, ...)
all_checks = Flapjack::Diner.checks
```
+<a name="update_checks"> </a>
+### update_checks
+
+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.)
+
+```ruby
+# update values for one checks
+Flapjack::Diner.update_checks(ID, :key => value, ...)
+
+# update values for multiple checks
+Flapjack::Diner.update_checks(ID1, ID2, ..., :key => value, ...)
+```
+
+Acceptable update field keys are
+
+`:enabled`
+
+as well as the linkage operations
+
+`:add_tag` and `:remove_tag`
+
+which take the name of the tag as the value.
+
+Returns true if updating succeeded or false if updating failed.
+
---
<a name="create_scheduled_maintenances_checks"> </a>
### create_scheduled_maintenances_checks
@@ -735,10 +801,10 @@
```
<a name="downtime_report_checks"> </a>
### downtime_report_checks
-Return a report on downtim 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.)
+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.)
```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