flapjack-diner 0.15 → 1.0.0.rc1

data/lib/flapjack-diner.rb

@@ -3,12 +3,12 @@ require 'json'
 require 'uri'
 require 'cgi'
 
-require "flapjack-diner/version"
-require "flapjack-diner/argument_validator"
+require 'flapjack-diner/version'
+require 'flapjack-diner/argument_validator'
 
 module Flapjack
   module Diner
-    SUCCESS_STATUS_CODES = [200, 204]
+    SUCCESS_STATUS_CODES = [200, 201, 204]
 
     include HTTParty
 
@@ -21,271 +21,337 @@ module Flapjack
       # NB: clients will need to handle any exceptions caused by,
       # e.g., network failures or non-parseable JSON data.
 
-      def entities
-        perform_get('/entities')
-      end
-
-      def checks(entity)
-        perform_get("/checks/#{escape(entity)}")
-      end
-
-      def status(entity, options = {})
-        check = options.delete(:check)
-        path = check.nil? ? "/status/#{escape(entity)}" : "/status/#{escape(entity)}/#{escape(check)}"
-        perform_get(path)
-      end
-
-      def bulk_status(options = {})
-        validate_bulk_params(options)
-        perform_get('/status', options)
-      end
-
-      # maybe rename 'create_acknowledgement!' ?
-      def acknowledge!(entity, check, options = {})
-        args = options.merge(:check => {entity => check})
-        validate_bulk_params(args)
-        perform_post('/acknowledgements', args)
+      # 1: Contacts
+      def create_contacts(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        data.each do |d|
+          validate_params(d) do
+            validate :query => [:first_name, :last_name, :email], :as => [:required, :string]
+            validate :query => :timezone,   :as => :string
+            validate :query => :tags,       :as => :array_of_strings
+          end
+        end
+        perform_post('/contacts', nil, :contacts => data)
       end
 
-      def bulk_acknowledge!(options = {})
-        validate_bulk_params(options)
-        perform_post('/acknowledgements', options)
+      def contacts(*ids)
+        extract_get('contacts', perform_get('/contacts', ids))
       end
 
-      # maybe rename 'create_test_notifications!' ?
-      def test_notifications!(entity, check, options = {})
-        args = options.merge(:check => {entity => check})
-        validate_bulk_params(args)
-        perform_post('/test_notifications', args)
+      def update_contacts(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'update_contacts' requires at least one contact id parameter" if ids.nil? || ids.empty?
+        validate_params(params) do
+            validate :query => [:first_name, :last_name,
+                                :email, :timezone], :as => :string
+            validate :query => :tags,       :as => :array_of_strings
+        end
+        ops = params.inject([]) do |memo, (k,v)|
+          case k
+          when :add_entity
+            memo << {:op    => 'add',
+                     :path  => '/contacts/0/links/entities/-',
+                     :value => v}
+          when :remove_entity
+            memo << {:op    => 'remove',
+                     :path  => "/contacts/0/links/entities/#{v}"}
+          # # Not supported yet due to id brokenness
+          # when :add_medium
+          #   memo << {:op    => 'add',
+          #            :path  => '/contacts/0/links/media/-',
+          #            :value => v}
+          # when :remove_medium
+          #   memo << {:op    => 'remove',
+          #            :path  => "/contacts/0/links/media/#{v}"}
+          when :add_notification_rule
+            memo << {:op    => 'add',
+                     :path  => '/contacts/0/links/notification_rules/-',
+                     :value => v}
+          when :remove_notification_rule
+            memo << {:op    => 'remove',
+                     :path  => "/contacts/0/links/notification_rules/#{v}"}
+          when :first_name, :last_name, :email, :timezone, :tags
+            memo << {:op    => 'replace',
+                     :path  => "/contacts/0/#{k.to_s}",
+                     :value => v}
+          end
+          memo
+        end
+        raise "'update_contacts' did not find any valid update fields" if ops.empty?
+        perform_patch("/contacts/#{escaped_ids(ids)}", nil, ops)
       end
 
-      def bulk_test_notifications!(options = {})
-        validate_bulk_params(options)
-        perform_post('/test_notifications', options)
+      def delete_contacts(*ids)
+        raise "'delete_contacts' requires at least one contact id parameter" if ids.nil? || ids.empty?
+        perform_delete('/contacts', ids)
       end
 
-      def create_scheduled_maintenance!(entity, check, options = {})
-        args = options.merge( check ? {:check => {entity => check}} : {:entity => entity} )
 
-        validate_bulk_params(args) do
-          validate :query => :start_time, :as => [:required, :time]
-          validate :query => :duration, :as => [:required, :integer]
+      # 2: Media
+      def create_contact_media(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'create_contact_media' requires at least one contact id parameter" if ids.nil? || ids.empty?
+        data.each do |d|
+          validate_params(d) do
+            validate :query => [:type, :address], :as => [:required, :string]
+            validate :query => [:interval, :rollup_threshold], :as => [:required, :integer]
+          end
         end
-
-        perform_post('/scheduled_maintenances', args)
+        perform_post("/contacts/#{escaped_ids(ids)}/media", nil, :media => data)
       end
 
-      def bulk_create_scheduled_maintenance!(options = {})
-        validate_bulk_params(options) do
-          validate :query => :start_time, :as => [:required, :time]
-          validate :query => :duration, :as => [:required, :integer]
-        end
-
-        perform_post('/scheduled_maintenances', options)
+      def media(*ids)
+        extract_get('media', perform_get('/media', ids))
       end
 
-      def delete_scheduled_maintenance!(entity, check, options = {})
-        args = options.merge( check ? {:check => {entity => check}} : {:entity => entity} )
-
-        validate_bulk_params(args) do
-          validate :query => :start_time, :as => :required
+      def update_media(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'update_media' requires at least one media id parameter" if ids.nil? || ids.empty?
+        validate_params(params) do
+          validate :query => :address,                       :as => :string
+          validate :query => [:interval, :rollup_threshold], :as => :integer
         end
-
-        perform_delete('/scheduled_maintenances', args)
-      end
-
-      def bulk_delete_scheduled_maintenance!(options = {})
-        validate_bulk_params(options) do
-          validate :query => :start_time, :as => :required
+        ops = params.inject([]) do |memo, (k,v)|
+          case k
+          when :address, :interval, :rollup_threshold
+            memo << {:op    => 'replace',
+                     :path  => "/media/0/#{k.to_s}",
+                     :value => v}
+          end
+          memo
         end
-
-        perform_delete('/scheduled_maintenances', options)
+        raise "'update_media' did not find any valid update fields" if ops.empty?
+        perform_patch("/media/#{escaped_ids(ids)}", nil, ops)
       end
 
-      def delete_unscheduled_maintenance!(entity, check, options = {})
-        args = options.merge( check ? {:check => {entity => check}} : {:entity => entity} )
-        validate_bulk_params(args) do
-          validate :query => :end_time, :as => :time
-        end
-        perform_delete('/unscheduled_maintenances', args)
+      def delete_media(*ids)
+        raise "'delete_media' requires at least one media id parameter" if ids.nil? || ids.empty?
+        perform_delete('/media', ids)
       end
 
-      def bulk_delete_unscheduled_maintenance!(options)
-        validate_bulk_params(options) do
-          validate :query => :end_time, :as => :time
+      # 2a: Pagerduty credentials
+      def create_contact_pagerduty_credentials(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'create_contact_pagerduty_credentials' requires at least one contact id parameter" if ids.nil? || ids.empty?
+        data.each do |d|
+          validate_params(d) do
+            validate :query => [:service_key, :subdomain, :username, :password], :as => [:required, :string]
+          end
         end
-        perform_delete('/unscheduled_maintenances', options)
+        perform_post("/contacts/#{escaped_ids(ids)}/pagerduty_credentials", nil, :pagerduty_credentials => data)
       end
 
-      def scheduled_maintenances(entity, options = {})
-        check = options.delete(:check)
-
-        validate_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
-        end
-
-        ec_path = entity_check_path(entity, check)
-        perform_get("/scheduled_maintenances/#{ec_path}", options)
+      def pagerduty_credentials(*ids)
+        extract_get('pagerduty_credentials', perform_get('/pagerduty_credentials', ids))
       end
 
-      def bulk_scheduled_maintenances(options = {})
-        validate_bulk_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
+      def update_pagerduty_credentials(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'update_pagerduty_credentials' requires at least one pagerduty_credentials id parameter" if ids.nil? || ids.empty?
+        validate_params(params) do
+          validate :query => [:service_key, :subdomain, :username, :password], :as => :string
         end
-
-        perform_get('/scheduled_maintenances', options)
-      end
-
-      def unscheduled_maintenances(entity, options = {})
-        check = options.delete(:check)
-
-        validate_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
+        ops = params.inject([]) do |memo, (k,v)|
+          case k
+          when :service_key, :subdomain, :username, :password
+            memo << {:op    => 'replace',
+                     :path  => "/pagerduty_credentials/0/#{k.to_s}",
+                     :value => v}
+          end
+          memo
         end
-
-        ec_path = entity_check_path(entity, check)
-        perform_get("/unscheduled_maintenances/#{ec_path}", options)
+        raise "'update_pagerduty_credentials did not find any valid update fields" if ops.empty?
+        perform_patch("/pagerduty_credentials/#{escaped_ids(ids)}", nil, ops)
       end
 
-      def bulk_unscheduled_maintenances(options = {})
-        validate_bulk_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
-        end
-
-        perform_get('/unscheduled_maintenances', options)
+      def delete_pagerduty_credentials(*ids)
+        raise "'delete_pagerduty_credentials' requires at least one pagerduty_credentials id parameter" if ids.nil? || ids.empty?
+        perform_delete('/pagerduty_credentials', ids)
       end
 
-      def outages(entity, options = {})
-        check = options.delete(:check)
 
-        validate_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
+      # 3: Notification Rules
+      def create_contact_notification_rules(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'create_contact_notification_rules' requires at least one contact id parameter" if ids.nil? || ids.empty?
+        data.each do |d|
+          validate_params(d) do
+            validate :query => [:entities, :regex_entities, :tags, :regex_tags,
+              :unknown_media, :warning_media, :critical_media], :as => :array_of_strings
+            validate :query => [:unknown_blackhole, :warning_blackhole, :critical_blackhole],
+              :as => :boolean
+          end
         end
-
-        ec_path = entity_check_path(entity, check)
-        perform_get("/outages/#{ec_path}", options)
+        perform_post("/contacts/#{escaped_ids(ids)}/notification_rules", nil, :notification_rules => data)
       end
 
-      def bulk_outages(options = {})
-        validate_bulk_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
-        end
-
-        perform_get('/outages', options)
+      def notification_rules(*ids)
+        extract_get('notification_rules', perform_get('/notification_rules', ids))
       end
 
-      def downtime(entity, options = {})
-        check = options.delete(:check)
-
-        validate_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
+      def update_notification_rules(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'update_notification_rules' requires at least one notification rule id parameter" if ids.nil? || ids.empty?
+        validate_params(params) do
+          validate :query => [:entities, :regex_entities, :tags, :regex_tags,
+            :unknown_media, :warning_media, :critical_media], :as => :array_of_strings
+          validate :query => [:unknown_blackhole, :warning_blackhole, :critical_blackhole],
+            :as => :boolean
         end
-
-        ec_path = entity_check_path(entity, check)
-
-        perform_get("/downtime/#{ec_path}", options)
-      end
-
-      def bulk_downtime(options = {})
-        validate_bulk_params(options) do
-          validate :query => [:start_time, :end_time], :as => :time
+        ops = params.inject([]) do |memo, (k,v)|
+          case k
+          when :entities, :regex_entities, :tags, :regex_tags,
+            :time_restrictions, :unknown_media, :warning_media, :critical_media,
+            :unknown_blackhole, :warning_blackhole, :critical_blackhole
+
+            memo << {:op    => 'replace',
+                     :path  => "/notification_rules/0/#{k.to_s}",
+                     :value => v}
+          end
+          memo
         end
-
-        perform_get('/downtime', options)
+        raise "'update_notification_rules' did not find any valid update fields" if ops.empty?
+        perform_patch("/notification_rules/#{escaped_ids(ids)}", nil, ops)
       end
 
-      def entity_tags(entity)
-        perform_get("/entities/#{escape(entity)}/tags")
+      def delete_notification_rules(*ids)
+        raise "'delete_notification_rules' requires at least one notification rule id parameter" if ids.nil? || ids.empty?
+        perform_delete('/notification_rules', ids)
       end
 
-      def add_entity_tags!(entity, *tags)
-        perform_post("/entities/#{escape(entity)}/tags", :tag => tags)
-      end
-
-      def delete_entity_tags!(entity, *tags)
-        perform_delete("/entities/#{escape(entity)}/tags", :tag => tags)
-      end
-
-      def contacts
-        perform_get('/contacts')
-      end
-
-      def contact(contact_id)
-        perform_get("/contacts/#{escape(contact_id)}")
-      end
-
-      def contact_tags(contact_id)
-        perform_get("/contacts/#{escape(contact_id)}/tags")
-      end
-
-      def contact_entitytags(contact_id)
-        perform_get("/contacts/#{escape(contact_id)}/entity_tags")
-      end
-
-      def add_contact_tags!(contact_id, *tags)
-        perform_post("/contacts/#{escape(contact_id)}/tags", :tag => tags)
-      end
-
-      # TODO better checking of provided data
-      def add_contact_entitytags!(contact_id, entity_tags = {})
-        perform_post("/contacts/#{escape(contact_id)}/entity_tags", :entity => entity_tags)
-      end
 
-      def delete_contact_tags!(contact_id, *tags)
-        perform_delete("/contacts/#{escape(contact_id)}/tags", :tag => tags)
+      # 4: Entities & 5: Checks
+      def create_entities(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        data.each do |d|
+          validate_params(d) do
+            validate :query => :id,   :as => [:required, :string]
+            validate :query => :name, :as => :string
+            validate :query => :tags, :as => :array_of_strings
+          end
+        end
+        perform_post('/entities', nil, :entities => data)
       end
 
-      # TODO better checking of provided data
-      def delete_contact_entitytags!(contact_id, entity_tags = {})
-        perform_delete("/contacts/#{escape(contact_id)}/entity_tags", :entity => entity_tags)
+      def entities(*ids)
+        extract_get('entities', perform_get('/entities', ids))
       end
 
-      def notification_rules(contact_id)
-        perform_get("/contacts/#{escape(contact_id)}/notification_rules")
+      def update_entities(*args)
+        ids, params, data = unwrap_ids_and_params(*args)
+        raise "'update_entities' requires at least one entity id parameter" if ids.nil? || ids.empty?
+        validate_params(params) do
+          validate :query => :name, :as => :string
+          validate :query => :tags, :as => :array_of_strings
+        end
+        ops = params.inject([]) do |memo, (k,v)|
+          case k
+          when :name, :tags
+            memo << {:op    => 'replace',
+                     :path  => "/entities/0/#{k.to_s}",
+                     :value => v}
+          when :add_contact
+            memo << {:op    => 'add',
+                     :path  => '/entities/0/links/contacts/-',
+                     :value => v}
+          when :remove_contact
+            memo << {:op    => 'remove',
+                     :path  => "/entities/0/links/contacts/#{v}"}
+          end
+          memo
+        end
+        raise "'update_entities' did not find any valid update fields" if ops.empty?
+        perform_patch("/entities/#{escaped_ids(ids)}", nil, ops)
       end
 
-      def notification_rule(rule_id)
-        perform_get("/notification_rules/#{escape(rule_id)}")
-      end
+      ['entities', 'checks'].each do |data_type|
 
-      def create_notification_rule!(rule)
-        perform_post('/notification_rules', rule)
-      end
+        define_method("create_scheduled_maintenances_#{data_type}") do |*args|
+          ids, params, data = unwrap_ids_and_params(*args)
+          raise "'create_scheduled_maintenances_#{data_type}' requires at least one #{data_type} id parameter" if ids.nil? || ids.empty?
+          data.each do |d|
+            validate_params(d) do
+              validate :query => :start_time, :as => [:required, :time]
+              validate :query => :duration,   :as => [:required, :integer]
+              validate :query => :summary,    :as => :string
+            end
+          end
+          perform_post("/scheduled_maintenances/#{data_type}", ids,
+            :scheduled_maintenances => data)
+        end
 
-      def update_notification_rule!(rule_id, rule)
-        perform_put("/notification_rules/#{escape(rule_id)}", rule)
-      end
+        define_method("create_unscheduled_maintenances_#{data_type}") do |*args|
+          ids, params, data = unwrap_ids_and_params(*args)
+          raise "'create_unscheduled_maintenances_#{data_type}' requires at least one #{data_type} id parameter" if ids.nil? || ids.empty?
+          data.each do |d|
+            validate_params(d) do
+              validate :query => :duration,   :as => [:required, :integer]
+              validate :query => :summary,    :as => :string
+            end
+          end
+          perform_post("/unscheduled_maintenances/#{data_type}", ids,
+            :unscheduled_maintenances => data)
+        end
 
-      def delete_notification_rule!(rule_id)
-        perform_delete("/notification_rules/#{escape(rule_id)}")
-      end
+        define_method("create_test_notifications_#{data_type}") do |*args|
+          ids, params, data = unwrap_ids_and_params(*args)
+          raise "'create_test_notifications_#{data_type}' requires at least one #{data_type} id parameter" if ids.nil? || ids.empty?
+          data.each do |d|
+            validate_params(d) do
+              validate :query => :summary,    :as => :string
+            end
+          end
+          perform_post("/test_notifications/#{data_type}", ids,
+            :test_notifications => data)
+        end
 
-      def contact_media(contact_id)
-        perform_get("/contacts/#{escape(contact_id)}/media")
-      end
+        define_method("update_unscheduled_maintenances_#{data_type}") do |*args|
+          ids, params, data = unwrap_ids_and_params(*args)
+          raise "'update_unscheduled_maintenances_#{data_type}' requires at least one #{data_type} id parameter" if ids.nil? || ids.empty?
+          validate_params(params) do
+            validate :query => :end_time, :as => :time
+          end
+          ops = params.inject([]) do |memo, (k,v)|
+            case k
+            when :end_time
+              memo << {:op    => 'replace',
+                       :path  => "/unscheduled_maintenances/0/#{k.to_s}",
+                       :value => v}
+            end
+            memo
+          end
+          raise "'update_unscheduled_maintenances_#{data_type}' did not find any valid update fields" if ops.empty?
+          perform_patch("/unscheduled_maintenances/#{data_type}", ids, ops)
+        end
 
-      def contact_medium(contact_id, media_type)
-        perform_get("/contacts/#{escape(contact_id)}/media/#{escape(media_type)}")
-      end
+        define_method("delete_scheduled_maintenances_#{data_type}") do |*args|
+          ids, params, data = unwrap_ids_and_params(*args)
+          raise "'delete_scheduled_maintenances_#{data_type}' requires at least one #{data_type} id parameter" if ids.nil? || ids.empty?
+          validate_params(params) do
+            validate :query => :start_time, :as => [:required, :time]
+          end
+          perform_delete("/scheduled_maintenances/#{data_type}", ids, params)
+        end
 
-      def update_contact_medium!(contact_id, media_type, media)
-        perform_put("/contacts/#{escape(contact_id)}/media/#{escape(media_type)}", media)
       end
 
-      def delete_contact_medium!(contact_id, media_type)
-        perform_delete("/contacts/#{escape(contact_id)}/media/#{escape(media_type)}")
-      end
 
-      def contact_timezone(contact_id)
-        perform_get("/contacts/#{escape(contact_id)}/timezone")
-      end
+      # 6: Reports
 
-      def update_contact_timezone!(contact_id, timezone)
-        perform_put("/contacts/#{escape(contact_id)}/timezone", :timezone => timezone)
-      end
+      ['entities', 'checks'].each do |data_type|
+        define_method("status_report_#{data_type}") do |*ids|
+          extract_get('status_reports', perform_get("/status_report/#{data_type}", ids))
+        end
 
-      def delete_contact_timezone!(contact_id)
-        perform_delete("/contacts/#{escape(contact_id)}/timezone")
+        ['scheduled_maintenance', 'unscheduled_maintenance', 'downtime', 'outage'].each do |report_type|
+          define_method("#{report_type}_report_#{data_type}") do |*args|
+            ids, params, data = unwrap_ids_and_params(*args)
+            validate_params(params) do
+              validate :query => [:start_time, :end_time], :as => :time
+            end
+            extract_get("#{report_type}_reports", perform_get("/#{report_type}_report/#{data_type}", ids, params))
+          end
+        end
       end
 
       def last_error
@@ -294,46 +360,46 @@ module Flapjack
 
       private
 
-      def perform_get(path, params = nil)
-        req_uri = build_uri(path, params)
+      def extract_get(name, result)
+        (result.nil? || result.is_a?(TrueClass)) ? result : result[name]
+      end
+
+      def perform_get(path, ids = [], data = [])
+        req_uri = build_uri(path, ids, data)
         logger.info "GET #{req_uri}" if logger
         response = get(req_uri.request_uri)
         handle_response(response)
       end
 
-      def perform_post(path, body = {})
-        req_uri = build_uri(path)
+      def perform_post(path, ids = [], data = [])
+        req_uri = build_uri(path, ids)
         if logger
           log_post = "POST #{req_uri}"
-          log_post << "\n  Params: #{body.inspect}" if body
+          log_post << "\n  Params: #{data.inspect}" if data
           logger.info log_post
         end
-        opts = body ? {:body => prepare_nested_query(body).to_json, :headers => {'Content-Type' => 'application/json'}} : {}
+        opts = data ? {:body => prepare_nested_query(data).to_json, :headers => {'Content-Type' => 'application/vnd.api+json'}} : {}
         response = post(req_uri.request_uri, opts)
         handle_response(response)
       end
 
-      def perform_put(path, body = {})
-        req_uri = build_uri(path)
+      def perform_patch(path, ids = [], data = [])
+        req_uri = build_uri(path, ids)
         if logger
-          log_put = "PUT #{req_uri}"
-          log_put << "\n  Params: #{body.inspect}" if body
-          logger.info log_put
+          log_patch = "PATCH #{req_uri}"
+          log_patch << "\n  Params: #{data.inspect}" if data
+          logger.info log_patch
         end
-        opts = body ? {:body => prepare_nested_query(body).to_json, :headers => {'Content-Type' => 'application/json'}} : {}
-        response = put(req_uri.request_uri, opts)
+        opts = data ? {:body    => prepare_nested_query(data).to_json,
+                       :headers => {'Content-Type' => 'application/json-patch+json'}} : {}
+        response = patch(req_uri.request_uri, opts)
         handle_response(response)
       end
 
-      def perform_delete(path, body = nil)
-        req_uri = build_uri(path)
-        if logger
-          log_delete = "DELETE #{req_uri}"
-          log_delete << "\n  Params: #{body.inspect}" if body
-          logger.info log_delete
-        end
-        opts = body ? {:body => prepare_nested_query(body).to_json, :headers => {'Content-Type' => 'application/json'}} : {}
-        response = delete(req_uri.request_uri, opts)
+      def perform_delete(path, ids = [], data = [])
+        req_uri = build_uri(path, ids, data)
+        logger.info "DELETE #{req_uri}" if logger
+        response = delete(req_uri.request_uri)
         handle_response(response)
       end
 
@@ -354,38 +420,10 @@ module Flapjack
         parsed_response
       end
 
-      def validate_bulk_params(query = {}, &validation)
-        errors = []
-
-        entities = query[:entity]
-        checks   = query[:check]
-
-        if entities && !entities.is_a?(String) &&
-           (!entities.is_a?(Array) || !entities.all? {|e| e.is_a?(String)})
-          raise ArgumentError.new("Entity argument must be a String, or an Array of Strings")
-        end
-
-        if checks && (!checks.is_a?(Hash) || !checks.all? {|k, v|
-          k.is_a?(String) && (v.is_a?(String) || (v.is_a?(Array) && v.all?{|vv| vv.is_a?(String)}))
-        })
-          raise ArgumentError.new("Check argument must be a Hash with keys String, values either String or Array of Strings")
-        end
-
-        if entities.nil? && checks.nil?
-          raise ArgumentError.new("Entity and/or check arguments must be provided")
-        end
-
-        validate_params(query, &validation)
-      end
-
       def validate_params(query = {}, &validation)
         ArgumentValidator.new(query).instance_eval(&validation) if block_given?
       end
 
-      def entity_check_path(entity, check)
-        check.nil? ? "#{escape(entity)}" : "#{escape(entity)}/#{escape(check)}"
-      end
-
       # copied from Rack::Utils -- builds the query string for GETs
       def build_nested_query(value, prefix = nil)
         if value.respond_to?(:iso8601)
@@ -410,10 +448,36 @@ module Flapjack
         end
       end
 
+      def escaped_ids(ids = [])
+        ids.collect{|id| CGI.escape(id.to_s)}.join(',')
+      end
+
       def escape(s)
         URI.encode_www_form_component(s)
       end
 
+      def unwrap_ids_and_params(*args)
+        ids    = []
+        params = {}
+        data   = []
+
+        args.each do |arg|
+          case arg
+          when Array
+            raise "Array arguments may only contain data Hashes" unless arg.all? {|a| a.is_a?(Hash)}
+            data += arg
+          when Hash
+            params.update(arg)
+          when String, Integer
+            ids << arg.to_s
+          else
+            raise "Arguments must be a Hash (parameters), String/Integer (ids), or Arrays of Hashes (data)"
+          end
+        end
+
+        [ids, params, data]
+      end
+
       # used for the JSON data hashes in POST, PUT, DELETE
       def prepare_nested_query(value)
         if value.respond_to?(:iso8601)
@@ -450,8 +514,11 @@ module Flapjack
         [protocol, host, port]
       end
 
-      def build_uri(path, params = nil)
+      def build_uri(path, ids = [], params = [])
         pr, ho, po = protocol_host_port
+        if !ids.nil? && !ids.empty?
+          path += '/' + escaped_ids(ids)
+        end
         URI::HTTP.build(:protocol => pr, :host => ho, :port => po,
           :path => path, :query => (params.nil? || params.empty? ? nil : build_nested_query(params)))
       end