pagerduty-sdk 1.0.2 → 1.0.3

data/lib/pagerduty/models/notes.rb

@@ -0,0 +1,7 @@
+class Notes
+  include Virtus.model
+
+  attribute :notes, Array[Note]
+end
+
+

data/lib/pagerduty/models/user.rb

@@ -26,24 +26,25 @@ class Pagerduty
     #end
 
     def log_entries(options={})
-      LogEntries.new(JSON.parse(curl({
+      LogEntries.new(curl({
         uri: "https://#@@subdomain.pagerduty.com/api/v1/users/#{self.id}/log_entries",
         params: options,
           method: 'GET'
-      }).body))
+      }))
     end
 
     def delete
       res = curl({
         uri: "https://#@@subdomain.pagerduty.com/api/v1/users/#{self.id}",
-        method: 'DELETE'
+        method: 'DELETE',
+        raw_response: true
       })
 
       res.code == '204' ? "Successfully deleted User #{self.id}" : JSON.parse(response.body)
     end
 
     def save
-      saved_user = User.new(JSON.parse(curl({
+      saved_user = User.new(curl({
         uri: "https://#@@subdomain.pagerduty.com/api/v1/users/#{self.id}",
         data: {
           role: self.role,
@@ -52,7 +53,7 @@ class Pagerduty
           time_zone: self.time_zone
         },
         method: 'PUT'
-      }).body)['user'])
+      })['user'])
 
       self.role = saved_user.role
       self.name = saved_user.name

data/lib/pagerduty/pagerduty.rb

@@ -1,6 +1,8 @@
 
 class Pagerduty
 
+  include Pagerduty::Core
+
   attr_reader :token
   attr_reader :subdomain
 
@@ -9,83 +11,49 @@ class Pagerduty
     @@subdomain = options[:subdomain]
   end
 
-  ###################################################################################
-  # def curl
-  #
-  # Purpose: Performs a CURL request
-  #
-  # Params: options<~Hash> - The options Hash to send
-  #           uri<~String> - The URI to curl
-  #           ssl<~Boolean><Optional> - Whether or not to use SSL
-  #           port<~Integer><Optional> - The port number to connect to
-  #           params<~Hash><Optional> - The params to send in the curl request
-  #           headers<~Hash><Optional> - The headers to send in the curl request
-  #           method<~String> - The HTTP method to perform
-  #           basic_auth<~Hash><Optional>
-  #             user<~String> - Basic auth user
-  #             password<~String> - Basic auth password
-  #
-  # Returns: <String>
-  ###################################################################################
-  def curl(options)
-
-    curl_request = {
-      ssl: true,
-      port: 443,
-      headers: {
-        "Content-Type" => "application/json",
-        "Authorization" => "Token token=#@@token",
-      },
-    }
-
-    options.merge! curl_request
-
-    url = URI.parse(options[:uri])
-
-    if options[:params]
-      parameters = options[:params].map { |k,v| "#{k}=#{v}" }.join("&")
-      url += "?#{parameters}"
-    end
-
-    http = Net::HTTP.new(url.host, 443)
-    http.use_ssl = true
-
-    request = case options[:method]
-              when 'DELETE'
-                Net::HTTP::Delete.new(url)
-              when 'GET'
-                Net::HTTP::Get.new(url)
-              when 'POST'
-                Net::HTTP::Post.new(url)
-              when 'PUT'
-                Net::HTTP::Put.new(url)
-              end
-
-    if options.has_key?(:data)
-      request.set_form_data(options[:data])
-    end
-
-    if options.has_key?(:basic_auth)
-      request.basic_auth options[:basic_auth][:user], options[:basic_auth][:password]
-    end
-
-    request.body = options[:body]
-
-    options[:headers].each { |key,val| request.add_field(key,val) }
-
-    if options[:method] == 'POST'
-      http.post(url.path,options[:data].to_json,options[:headers])
-    elsif options[:method] == 'PUT'
-      http.put(url.path,options[:data].to_json,options[:headers])
-    else
-      http.request(request)
-    end
-  end
 
+  # Check a Hash object for expected keys
+  #
+  # ==== Parameters
+  # * 'keys'<~Array><~Object> - An array of objects expected to be found as keys in the supplied Hash
+  # * 'options'<~Hash> - The Hash to perform the check on
+  #
+  # ==== Returns
+  # * Boolean
+  #
   def has_requirements?(keys,options)
     (keys - options.keys).empty?
   end
 
+
+  # List existing alerts for a given time range, optionally filtered by type (SMS, Email, Phone, or Push)
+  #
+  # ==== Parameters
+  # * params<~Hash>
+  #   * 'since'<~String>: The start of the date range over which you want to search. The time element is optional.
+  #   * 'until'<~String>: The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #   * 'filter'<~String>: Returns only the alerts of the said types. Can be one of SMS, Email, Phone, or Push.
+  #   * 'time_zone'<~TimeZone>: Time zone in which dates in the result will be rendered. Defaults to account time zone.
+  #
+  # ==== Returns
+  # * 'alerts'<~Array><~Alerts>
+  #   * 'id'<~String>
+  #   * 'type'<~String>
+  #   * 'started_at'<~String>
+  #   * 'user'<~Pagerduty::User>
+  #     * 'id'<~String>
+  #     * 'name'<~String>
+  #     * 'email'<~String>
+  #     * 'time_zone'<~String>
+  #     * 'color'<~String>
+  #     * 'avatar_url'<~String>
+  #     * 'user_url'<~String>
+  #     * 'invitation_sent'<~Boolean>
+  #     * 'marketing'<~String>
+  #     * 'marketing_opt_out'<~String>
+  #     * 'type'<~String>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/alerts/list]
   def alerts(options={})
 
     unless has_requirements? [:since, :until], options
@@ -94,26 +62,106 @@ class Pagerduty
       return
     end
 
-    JSON.parse(curl({
+    Alerts.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/alerts",
       params: options,
       method: 'GET'
-    }).body)['alerts'].inject([]) { |alerts, alert|
-      alerts << Alert.new(alert)
-    }
-
+    }))
   end
 
+  # List all the existing escalation policies.
+  #
+  # ==== Parameters
+  # * params<~Hash>
+  #   * 'query'<~String> - Filters the result, showing only the escalation policies whose names match the query.
+  #   * 'include'<~Array> - An array of extra data to include with the escalation policies.
+  #
+  # ==== Returns
+  # * <~Array>
+  #   * <~EscalationPolicy>
+  #     * 'id'<~String> - Id of request
+  #     * 'name'<~String> - The policy name
+  #     * 'escalation_rules'<~Array><~EscalationRule>
+  #       * 'escalation_delay_in_minutes'<~Integer> - The escalation delay in minutes
+  #       * 'rule_object'<~RuleObject>:
+  #         * 'id'<~String> - The id of the rule object
+  #         * 'name'<~String> - The name of the rule
+  #         * 'type'<~String> - The type of rule
+  #         * 'email'<~String> - The email address associated with the rule
+  #         * 'time_zone'<~String> - The time zone for the rule
+  #         * 'color'<~String> - The display color of the rule
+  #     * 'services'<~Array><~EscalationService>:
+  #       * 'id'<~String> -
+  #       * 'name'<~String> -
+  #       * 'service_url'<~String> -
+  #       * 'service_key'<~String> -
+  #       * 'auto_resolve_timeout'<~String> -
+  #       * 'acknowledgement_timeout'<~String> -
+  #       * 'created_at'<~String> -
+  #       * 'deleted_at'<~String> -
+  #       * 'status'<~String> -
+  #       * 'last_incident_timestamp'<~String> -
+  #       * 'email_incident_creation'<~String> -
+  #       * 'incident_counts'<~String> -
+  #       * 'email_filter_mode'<~String> -
+  #       * 'type'<~String> -
+  #     * 'num_loops'<~Integer> - The number of times to loop the incident
+  #   * 'limit'<~Integer>
+  #   * 'offset'<~Integer>
+  #   * 'total'<~Integer>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/escalation_policies/list]
   def escalation_policies(options={})
-    JSON.parse(curl({
+    curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/escalation_policies",
       params: { 'query' => options[:query] },
       method: 'GET'
-    }).body)['escalation_policies'].inject([]) { |policies, policy|
+    })['escalation_policies'].inject([]) { |policies, policy|
       policies << EscalationPolicy.new(policy)
     }
   end
 
+  # Creates a new escalation policy. There must be at least one existing 
+  # escalation rule added to create a new escalation policy
+  #
+  # ==== Parameters
+  # * params<~Hash>
+  #   * 'name'<~String> - The desired name for the escalation policy
+  #   * 'repeat_enabled'<~Boolean> - Whether or not to allow this policy to repeat its escalation rules after the last rule is finished. Defaults to false.
+  #   * 'num_loops'<~Integer> - The number of times to loop over the set of rules in this escalation policy.
+  #   * 'escalation_rules'<~Array> - The escalation rules for this policy. The ordering and available parameters are found under the Escalation Rules API. There must be at least one rule to create a new escalation policy.
+  #
+  # ==== Returns
+  # * response<~EscalationPolicy>:
+  #   * 'id'<~String> - Id of request
+  #   * 'name'<~String> - The policy name
+  #   * 'escalation_rules'<~Array><~EscalationRule>
+  #     * 'escalation_delay_in_minutes'<~Integer> - The escalation delay in minutes
+  #     * 'rule_object'<~RuleObject>:
+  #       * 'id'<~String> - The id of the rule object
+  #       * 'name'<~String> - The name of the rule
+  #       * 'type'<~String> - The type of rule
+  #       * 'email'<~String> - The email address associated with the rule
+  #       * 'time_zone'<~String> - The time zone for the rule
+  #       * 'color'<~String> - The display color of the rule
+  #   * 'services'<~Array><~EscalationService>:
+  #     * 'id'<~String> -
+  #     * 'name'<~String> -
+  #     * 'service_url'<~String> -
+  #     * 'service_key'<~String> -
+  #     * 'auto_resolve_timeout'<~String> -
+  #     * 'acknowledgement_timeout'<~String> -
+  #     * 'created_at'<~String> -
+  #     * 'deleted_at'<~String> -
+  #     * 'status'<~String> -
+  #     * 'last_incident_timestamp'<~String> -
+  #     * 'email_incident_creation'<~String> -
+  #     * 'incident_counts'<~String> -
+  #     * 'email_filter_mode'<~String> -
+  #     * 'type'<~String> -
+  #   * 'num_loops'<~Integer> - The number of times to loop the incident
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/escalation_policies/create]
   def create_escalation_policy(options={})
 
     if options[:escalation_rules]
@@ -122,45 +170,121 @@ class Pagerduty
       }
     end
 
-    EscalationPolicy.new(JSON.parse(curl({
+    EscalationPolicy.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/escalation_policies",
       data: options,
       method: 'POST'
-    }).body)['escalation_policy'])
+    })['escalation_policy'])
 
   end
 
+  # Get information about an existing escalation policy and its rules
+  #
+  # ==== Parameters
+  #
+  # * params<~Hash>
+  #   * 'id'<~String>: The id of the escalation policy
+  #
+  # ==== Returns
+  # * response<Array><~Pagerduty::EscalationPolicy>:
+  #   * 'id'<~String> - Id of request
+  #   * 'name'<~String> - The name of the policy
+  #   * 'description'<~String> - Policy description
+  #   * 'escalation_rules'<~Array><~RuleObject>:
+  #     * 'id'<~String> - The id of the rule object
+  #     * 'name'<~String> - The name of the rule
+  #     * 'type'<~String> - The type of rule
+  #     * 'email'<~String> - The email address associated with the rule
+  #     * 'time_zone'<~String> - The time zone for the rule
+  #     * 'color'<~String> - The display color of the rule
+  #   * 'services'<~Array><~EscalationService>:
+  #     * 'id'<~String> -
+  #     * 'name'<~String> -
+  #     * 'service_url'<~String> -
+  #     * 'service_key'<~String> -
+  #     * 'auto_resolve_timeout'<~String> -
+  #     * 'acknowledgement_timeout'<~String> -
+  #     * 'created_at'<~String> -
+  #     * 'deleted_at'<~String> -
+  #     * 'status'<~String> -
+  #     * 'last_incident_timestamp'<~String> -
+  #     * 'email_incident_creation'<~String> -
+  #     * 'incident_counts'<~String> -
+  #     * 'email_filter_mode'<~String> -
+  #     * 'type'<~String> -
+  #   * 'num_loops'<~Integer> - The number of times to loop the incident
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/escalation_policies/show]
   def get_escalation_policy(options={})
-    EscalationPolicy.new(JSON.parse(curl({
+    EscalationPolicy.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/escalation_policies/#{options[:id]}",
       method: 'GET'
-    }).body)['escalation_policy'])
+    })['escalation_policy'])
   end
 
+  # List all the escalation rules for an existing escalation policy
+  #
+  # ==== Parameters
+  #
+  # * params<~Hash>
+  #   * 'escalation_policy_id'<~String>: The id of the escalation policy
+  #
+  # ==== Returns
+  # * response<Array><~Pagerduty::EscalationRule>:
+  #   * 'id'<~String> - Id of request
+  #   * 'escalation_delay_in_minutes'<~Integer> - The escalation delay in minutes
+  #   * <~RuleObject>:
+  #     * 'id'<~String> - The id of the rule object
+  #     * 'name'<~String> - The name of the rule
+  #     * 'type'<~String> - The type of rule
+  #     * 'email'<~String> - The email address associated with the rule
+  #     * 'time_zone'<~String> - The time zone for the rule
+  #     * 'color'<~String> - The display color of the rule
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/escalation_policies/escalation_rules/list]
   def escalation_rules(options)
-    JSON.parse(curl({
+    curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/escalation_policies/#{options[:escalation_policy_id]}/escalation_rules",
       params: { 'query' => options[:query] },
       method: 'GET'
-    }).body)['escalation_rules'].inject([]) { |rules, rule|
+    })['escalation_rules'].inject([]) { |rules, rule|
       rules << EscalationRule.new(rule)
     }
   end
 
+  # Show the escalation rule for an existing escalation policy
+  #
+  # ==== Parameters
+  # * params<~Hash>
+  #   * 'escalation_policy_id'<~String>: The id of the escalation policy the rule resides in
+  #   * 'rule_id'<~String>: The id of the rule to retrieve
+  #
+  # ==== Returns
+  # * response<~Pagerduty::EscalationRule>:
+  #   * 'id'<~String> - Id of request
+  #   * 'escalation_delay_in_minutes'<~Integer> - The escalation delay in minutes
+  #   * <~RuleObject>:
+  #     * 'id'<~String> - The id of the rule object
+  #     * 'name'<~String> - The name of the rule
+  #     * 'type'<~String> - The type of rule
+  #     * 'email'<~String> - The email address associated with the rule
+  #     * 'time_zone'<~String> - The time zone for the rule
+  #     * 'color'<~String> - The display color of the rule
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/escalation_policies/escalation_rules/show]
   def get_escalation_rule(options={})
-    JSON.parse(curl({
+    EscalationRule.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/escalation_policies/#{options[:escalation_policy_id]}/escalation_rules/#{options[:rule_id]}",
       method: 'GET'
-    }).body)
+    })['escalation_rule'])
   end
 
   # Retrieve all incidents
   #
   # ==== Parameters
-  #
   # * params<~Hash>
-  #   * 'since'<~String>: The start of the date range over which to search
-  #   * 'until'<~String>: The end of the date range over which to search
+  #   * 'since'<~String>: The start of the date range over which you want to search. The time element is optional.
+  #   * 'until'<~String>: The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
   #   * 'date_range'<~String>: When set to 'all' the 'since' and 'until' params are ignored. Use this to get all incidents since the account was created
   #   * 'fields'<~String>: Used to restrict the properties of each incident returned to a set of pre-defined fields. If omitted, returned incidents have all fields present. See below for a list of possible fields.
   #   * 'status'<~String>: Returns only the incidents currently in the passed status(es). Valid status options are triggered, acknowledged, and resolved. More status codes may be introduced in the future.
@@ -204,163 +328,788 @@ class Pagerduty
   #
   # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/incidents/list]
   def incidents(options={})
-    JSON.parse(curl({
+
+    Pagerduty::Incidents.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/incidents",
       params: {
         since: options[:since] || (Time.now - 1.day).strftime("%Y-%m-%d"),
         :until => options[:until] || (Time.now + 1.day).strftime("%Y-%m-%d"),
       },
       method: 'GET'
-    }).body)['incidents'].inject([]) { |incidents, incident|
-      incidents << Incident.new(incident)
-    }
+    }))
   end
 
+
+  # Show detailed information about an incident. Accepts either an incident id, or an incident number
+  #
+  # ==== Parameters
+  # options<~Hash>
+  #   * 'id'<~String> - The incident id or incident number to look for
+  #
+  # ==== Returns
+  # * <~Pagerduty::Incident>:
+  #   * 'id'<~String> - Id of request
+  #   * 'incident_number'<~String>:
+  #   * 'created_on'<~String>:
+  #   * 'status'<~String>:
+  #   * 'html_url'<~String>:
+  #   * 'incident_key'<~String>:
+  #   * 'service'<~Pagerduty::Service>
+  #     * 'id'<~String>:
+  #     * 'name'<~String>:
+  #     * 'html_url'<~String>:
+  #     * 'deleted_at'<~String>:
+  #   * 'escalation_policy'<~String>:
+  #   * 'assigned_to_user'<~String>:
+  #   * 'trigger_summary_data'<~String>:
+  #   * 'trigger_details_html_url'<~String>:
+  #   * 'trigger_type'<~String>:
+  #   * 'last_status_change_on'<~String>:
+  #   * 'last_status_change_by'<~Pagerduty::User>:
+  #     * 'id'<~String>:
+  #     * 'name'<~String>:
+  #     * 'email'<~String>:
+  #     * 'html_url'<~String>:
+  #   * 'number_of_escalations'<~Integer>:
+  #   * 'resolved_by_user'<~Pagerduty::ResolvedByUser>:
+  #     * 'id'<~String>:
+  #     * 'name'<~String>:
+  #     * 'email'<~String>:
+  #     * 'html_url'<~String>:
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/incidents/show]
   def get_incident(options={})
-    incidents.detect { |incident| incident.id == options[:id] } || 'No results'
+    incidents.incidents.detect { |incident|
+      incident.id == options[:id] || incident.incident_number == options[:id]
+    } || 'No results'
   end
 
+  # Use this query if you are simply looking for the count of incidents that match a given query. This should be used if you don't need access to the actual incident details.
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'since'<~String> - The start of the date range over which you want to search. The time element is optional.
+  #   * 'until'<~String> - The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #   * 'date_range'<~String> - When set to all, the since and until parameters and defaults are ignored. Use this to get all counts since the account was created.
+  #   * 'status'<~String> - Only counts the incidents currently in the passed status(es). Valid status options are triggered, acknowledged, and resolved. More status codes may be introduced in the future.
+  #   * 'incident_key'<~String> - Only counts the incidents with the passed de-duplication key. See the PagerDuty Integration API docs for further details.
+  #   * 'service'<~String> - Only counts the incidents associated with the passed service(s). This is expecting one or more service IDs. Separate multiple ids by a comma.
+  #   * 'assigned_to_user'<~String> - Only counts the incidents currently assigned to the passed user(s). This is expecting one or more user IDs. Note: When using the assigned_to_user filter, you will only count incidents with statuses of triggered or acknowledged. This is because resolved incidents are not assigned to any user. Separate multiple ids by a comma.
+  #
+  # ==== Returns
+  # <~Hash>
+  #   * 'total'<~Integer>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/incidents/count]
   def get_incident_counts(options={})
-    JSON.parse(curl({
+    curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/incidents/count",
       params: options,
       method: 'GET',
-    }).body)
+    })
   end
 
+  # List users of your PagerDuty account, optionally filtered by a search query.
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'query'<~String> - Filters the result, showing only the users whose names or email addresses match the query
+  #   * 'include'<~Array> - Array of additional details to include. This API accepts contact_methods, and notification_rules
+  #
+  # ==== Returns
+  # * <~Users>
+  #   * 'users'<~Array>:
+  #     * 'user'<~Pagerduty::User>:
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'email'<~String>
+  #       * 'time_zone'<~String>
+  #       * 'color'<~String>
+  #       * 'role'<~String>
+  #       * 'avatar_url'<~String>
+  #       * 'user_url'<~String>
+  #       * 'invitation_sent'<~Boolean>
+  #       * 'marketing'<~String>
+  #       * 'marketing_opt_out'<~String>
+  #       * 'type'<~String>
+  # * 'active_account_users'<~Integer>
+  # * 'limit'<~Integer>
+  # * 'offset'<~Integer>
+  # * 'total'<~Integer>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/users/list]
   def get_users(options={})
-    Users.new(JSON.parse(curl({
+    Users.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/users",
-      params: { query: options[:query] },
+      params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # Get information about an existing user.
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'id'<~String> - The ID of the user to retrieve
+  #
+  # ==== Returns
+  # * 'user'<~User>:
+  #   * 'time_zone'<~String>
+  #   * 'color'<~String>
+  #   * 'email'<~String>
+  #   * 'avatar_url'<~String>
+  #   * 'user_url'<~String>
+  #   * 'invitation_sent'<~Boolean>
+  #   * 'role'<~String>
+  #   * 'name'<~String>
+  #   * 'id'<~String>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/users/show]
   def get_user(options={})
     get_users.users.detect { |user| user.id == options[:id] }
   end
 
+  # Create a new user for your account. An invite email will be sent asking the user to choose a password
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'role'<~String> - The user's role. This can either be admin or user and defaults to user if not specificed
+  #   * 'name'<~String> - The name of the user
+  #   * 'email'<~String> - The email of the user. The newly created user will receive an email asking to confirm the subscription
+  #   * 'time_zone'<~String> - The time zone the user is in. If not specified, the time zone of the account making the API call will be used
+  #   * 'requester_id'<~String> - The user id of the user creating the user. This is only needed if you are using token based authentication
+  #
+  # ==== Returns
+  # * 'user'<~User>
+  #   * 'time_zone'<~String>
+  #   * 'color'<~String>
+  #   * 'email'<~String>
+  #   * 'avatar_url'<~String>
+  #   * 'user_url'<~String>
+  #   * 'invitation_sent'<~String>
+  #   * 'role'<~String>
+  #   * 'name'<~String>
+  #   * 'id'<~String>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/users/create]
   def create_user(options={})
-    User.new(JSON.parse(curl({
+    User.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/users",
       data: options,
       method: 'POST'
-    }).body)['user'])
+    })['user'])
   end
 
+  # List existing notes for the specified incident.
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'id' - The id of the incident to retrieve notes from
+  #
+  # ==== Returns
+  # * <~Notes>:
+  #   * 'notes'<~Array>:
+  #     * ~<Note>:
+  #       * 'id' - 
+  #       * 'user'<~Pagerduty::User>:
+  #         * 'id'<~String>
+  #         * 'name'<~String>
+  #         * 'email'<~String>
+  #         * 'time_zone'<~String>
+  #         * 'color'<~String>
+  #         * 'role'<~String>
+  #         * 'avatar_url'<~String>
+  #         * 'user_url'<~String>
+  #         * 'invitation_sent'<~Boolean>
+  #         * 'marketing'<~String>
+  #         * 'marketing_opt_out'<~String>
+  #         * 'type'<~String>
+  #       * 'content'<~String> - 
+  #       * 'created_at'<~String> - 
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/incidents/notes/list]
   def notes(id)
-    JSON.parse(curl({
+    Notes.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/incidents/#{id}/notes",
       method: 'GET'
-    }).body)['notes'].inject([]) { |notes, note|
-      notes << Note.new(note)
-    }
+    }))
   end
 
+
+  # List all incident log entries across the entire account
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'time_zone'<~String> -
+  #   * 'since'<~String> - The start of the date range over which you want to search. The time element is optional.
+  #   * 'until'<~String> - The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #   * 'is_overview'<~Boolean> -
+  #   * 'until'<~Array> - The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #   * 'include'<~Array> - The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #
+  # ==== Returns
+  # * 'log_entries'<~Array>:
+  #   * <~Pagerduty::LogEntry>:
+  #     * 'id'<~String> -
+  #     * 'type'<~String> -
+  #     * 'created_at'<~String> -
+  #     * 'note'<~String> -
+  #     * 'agent'<~Pagerduty::User>
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'email'<~String>
+  #       * 'time_zone'<~String>
+  #       * 'color'<~String>
+  #       * 'role'<~String>
+  #       * 'avatar_url'<~String>
+  #       * 'user_url'<~String>
+  #       * 'invitation_sent'<~Boolean>
+  #       * 'marketing'<~String>
+  #       * 'marketing_opt_out'<~String>
+  #       * 'type'<~String>
+  #     * 'user'<~Pagerduty::User>
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'email'<~String>
+  #       * 'time_zone'<~String>
+  #       * 'color'<~String>
+  #       * 'role'<~String>
+  #       * 'avatar_url'<~String>
+  #       * 'user_url'<~String>
+  #       * 'invitation_sent'<~Boolean>
+  #       * 'marketing'<~String>
+  #       * 'marketing_opt_out'<~String>
+  #       * 'type'<~String>
+  #     * 'channel'<~Hash>
+  #       * 'type'
+  # * 'limit'<~Integer> -
+  # * 'offset'<~Integer> -
+  # * 'total'<~Integer> -
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/log_entries/list]
   def get_log_entries(options={})
-    LogEntries.new(JSON.parse(curl({
+    LogEntries.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/log_entries",
       params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # Get details for a specific incident log entry. This method provides additional information you can use to get at raw event data
+  #
+  # ==== Parameters
+  # * options<~Hash>
+  #   * 'time_zone'<~TimeZone> -
+  #   * 'include'<~Array> -
+  #
+  # ==== Returns
+  # * 'log_entry'<~LogEntry>
+  #  * 'id'<~String>
+  #  * 'type'<~String>
+  #  * 'created_at'<~String>
+  #    * 'agent'<~Pagerduty::User>
+  #      * 'id'<~String>
+  #      * 'name'<~String>
+  #      * 'email'<~String>
+  #      * 'time_zone'<~String>
+  #      * 'color'<~String>
+  #      * 'role'<~String>
+  #      * 'avatar_url'<~String>
+  #      * 'user_url'<~String>
+  #      * 'invitation_sent'<~Boolean>
+  #      * 'marketing'<~String>
+  #      * 'marketing_opt_out'<~String>
+  #      * 'type'<~String>
+  #    * 'user'<~Pagerduty::User>
+  #      * 'id'<~String>
+  #      * 'name'<~String>
+  #      * 'email'<~String>
+  #      * 'time_zone'<~String>
+  #      * 'color'<~String>
+  #      * 'role'<~String>
+  #      * 'avatar_url'<~String>
+  #      * 'user_url'<~String>
+  #      * 'invitation_sent'<~Boolean>
+  #      * 'marketing'<~String>
+  #      * 'marketing_opt_out'<~String>
+  #      * 'type'<~String>
+  #    * 'channel'<~Hash>
+  #      * 'summary'<~String>
+  #      * 'type'<~String>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/log_entries/show]
   def get_log_entry(options={})
-    LogEntry.new(JSON.parse(curl({
+    LogEntry.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/log_entries/#{options[:id]}",
       params: options,
       method: 'GET'
-    }).body)['log_entry'])
+    })['log_entry'])
   end
 
+  # Get high level statistics about the number of alerts (SMSes, phone calls and emails) sent for the desired time period, summed daily, weekly or monthly.
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'since'<~String> - The start of the date range over which you want to search. The time element is optional.
+  #   * 'until'<~String> - The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #   * 'rollup'<~String> - Possible values are daily,  weekly or monthly. Specifies the bucket duration for each summation. Defaults to monthly. (Example: A time window of two years (based on since and until) with a rollup of monthly will result in 24 sets of data points being returned (one for each month in the span))
+  #
+  # ==== Returns
+  # * 'alerts'<~Array>
+  #   * <~Pagerduty::Reports::Alert>:
+  #     * 'number_of_alerts'<~Integer>
+  #     * 'number_of_phone_alerts'<~Integer>
+  #     * 'number_of_sms_alerts'<~Integer>
+  #     * 'number_of_email_alerts'<~Integer>
+  #     * 'start'<~String>
+  #     * 'end'<~String>
+  #   * 'total_number_of_alerts'<~Integer> -
+  #   * 'total_number_of_phone_alerts'<~Integer> -
+  #   * 'total_number_of_sms_alerts'<~Integer> -
+  #   * 'total_number_of_email_alerts'<~Integer> -
+  #   * 'total_number_of_billable_alerts'<~Integer> -
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/reports/alerts_per_time]
   def alerts_per_time(options={})
-    Pagerduty::Reports::Alerts.new(JSON.parse(curl({
+    Pagerduty::Reports::Alerts.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/reports/alerts_per_time",
       params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # Get high level statistics about the number of incidents created for the desired time period, summed daily, weekly or monthly
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'since'<~String>: The start of the date range over which you want to search. The time element is optional.
+  #   * 'until'<~String>: The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
+  #   * 'rollup'<~String>: Possible values are daily,  weekly or monthly. Specifies the bucket duration for each summation. Defaults to monthly. (Example: A time window of two years (based on since and until) with a rollup of monthly will result in 24 sets of data points being returned (one for each month in the span))
+  #
+  # ==== Returns
+  # * <~Pagerduty::Reports::Incidents>
+  #   * 'incidents'<~Array>
+  #     * <~Pagerduty::Reports::Incident>
+  #       * 'number_of_incidents'<~Integer> -
+  #       * 'start'<~String> -
+  #       * 'end'<~String> -
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/reports/incidents_per_time]
   def incidents_per_time(options={})
-    Pagerduty::Reports::Incidents.new(JSON.parse(curl({
+    Pagerduty::Reports::Incidents.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/reports/incidents_per_time/",
       params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # List existing maintenance windows, optionally filtered by service, or whether they are from the past, present or future
+  #
+  # ==== Parameters
+  # * options<~Hash>
+  #   * 'query'<~String> - Filters the results, showing only the maintenance windows whose descriptions contain the query
+  #   * 'service_ids'<~Array> - An array of service IDs, specifying services whose maintenance windows shall be returned
+  #   * 'filter'<~String> - Only return maintenance windows that are of this type. Possible values are past, future, ongoing. If this parameter is omitted, all maintenance windows will be returned
+  #
+  # ==== Returns
+  # * <~Pagerduty::MaintenanceWindows>
+  #   * 'maintenance_windows'<~Array>
+  #     * <~Pagerduty::MaintenanceWindow>
+  #       * 'id'<~String>
+  #       * 'sequence_number'<~Integer>
+  #       * 'start_time'<~String>
+  #       * 'end_time'<~String>
+  #       * 'description'<~String>
+  #       * 'created_by'<~Pagerduty::User>
+  #         * 'id'<~String>
+  #         * 'name'<~String>
+  #         * 'email'<~String>
+  #         * 'time_zone'<~String>
+  #         * 'color'<~String>
+  #         * 'role'<~String>
+  #         * 'avatar_url'<~String>
+  #         * 'user_url'<~String>
+  #         * 'invitation_sent'<~Boolean>
+  #         * 'marketing'<~String>
+  #         * 'marketing_opt_out'<~String>
+  #         * 'type'<~String>
+  #       * 'services'<~Array>
+  #         * <~Service>
+  #           * 'id'<~String>
+  #           * 'name'<~String>
+  #           * 'html_url'<~String>
+  #           * 'delete_at'<~String>
+  #       * 'service_ids'<~Array> - An array of strings of all the service IDs associated with the maintenance window
+  # * 'limit'<~Integer>
+  # * 'offset'<~Integer>
+  # * 'total'<~Integer>
+  # * 'query'<~Integer>
+  # * 'query'<~String>
+  # * 'counts'<~Pagerduty::MaintenanceWindow::Count>
+  #   * 'ongoing'<~Integer>
+  #   * 'future'<~Integer>
+  #   * 'past'<~Integer>
+  #   * 'all'<~Integer>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/maintenance_windows/list]
   def get_maintenance_windows(options={})
-    Pagerduty::MaintenanceWindows.new(JSON.parse(curl({
+    Pagerduty::MaintenanceWindows.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/maintenance_windows",
       params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # Get details about an existing maintenance window
+  #
+  # ==== Parameters
+  # * 'options'<~Hash>:
+  #   * 'id'<~String> - The id of the maintenance window to retrieve
+  #
+  # ==== Returns
+  # * <~Pagerduty::MaintenanceWindow>
+  #   * 'id'<~String>
+  #   * 'sequence_number'<~Integer>
+  #   * 'start_time'<~String>
+  #   * 'end_time'<~String>
+  #   * 'description'<~String>
+  #   * 'created_by'<~Pagerduty::User>
+  #     * 'id'<~String>
+  #     * 'name'<~String>
+  #     * 'email'<~String>
+  #     * 'time_zone'<~String>
+  #     * 'color'<~String>
+  #     * 'role'<~String>
+  #     * 'avatar_url'<~String>
+  #     * 'user_url'<~String>
+  #     * 'invitation_sent'<~Boolean>
+  #     * 'marketing'<~String>
+  #     * 'marketing_opt_out'<~String>
+  #     * 'type'<~String>
+  #   * 'services'<~Array>
+  #     * <~Service>
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'html_url'<~String>
+  #       * 'delete_at'<~String>
+  #   * 'service_ids'<~Array> - An array of strings of all the service IDs associated with the maintenance window
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/maintenance_windows/show]
   def get_maintenance_window(options={})
-    Pagerduty::MaintenanceWindow.new(JSON.parse(curl({
+    Pagerduty::MaintenanceWindow.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/maintenance_windows/#{options[:id]}",
       params: options,
       method: 'GET'
-    }).body)['maintenance_window'])
+    })['maintenance_window'])
   end
 
+  # Create a new maintenance window for the specified services. No new incidents will be created for a service that is currently in maintenance
+  #
+  # ==== Parameters
+  # * 'options'<~Hash>
+  #   * 'requester_id'<~String>
+  #   * 'maintenance_window'<~Hash>
+  #     * 'start_time'<~String>
+  #     * 'end_time'<~String>
+  #     * 'description'<~String>
+  #     * 'service_ids'<~Array>
+  #
+  # ==== Returns
+  # * <~Pagerduty::MaintenanceWindow>
+  #   * 'id'<~String>
+  #   * 'sequence_number'<~Integer>
+  #   * 'start_time'<~String>
+  #   * 'end_time'<~String>
+  #   * 'description'<~String>
+  #   * 'created_by'<~Pagerduty::User>
+  #     * 'id'<~String>
+  #     * 'name'<~String>
+  #     * 'email'<~String>
+  #     * 'time_zone'<~String>
+  #     * 'color'<~String>
+  #     * 'role'<~String>
+  #     * 'avatar_url'<~String>
+  #     * 'user_url'<~String>
+  #     * 'invitation_sent'<~Boolean>
+  #     * 'marketing'<~String>
+  #     * 'marketing_opt_out'<~String>
+  #     * 'type'<~String>
+  #   * 'services'<~Array>
+  #     * <~Service>
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'html_url'<~String>
+  #       * 'delete_at'<~String>
+  #   * 'service_ids'<~Array> - An array of strings of all the service IDs associated with the maintenance window
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/maintenance_windows/create]
   def create_maintenance_window(options={})
-    Pagerduty::MaintenanceWindow.new(JSON.parse(curl({
+    Pagerduty::MaintenanceWindow.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/maintenance_windows",
       data: options,
       method: 'POST'
-    }).body)['maintenance_window'])
+    })['maintenance_window'])
   end
 
+  # List existing on-call schedules
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'query'<~String> - Filters the result, showing only the schedules whose name matches the query
+  #   * 'requester_id'<~String> - The user id of the user making the request. This will be used to generate the calendar private urls. This is only needed if you are using token based authentication
+  #
+  # ==== Returns
+  # * <~Pagerduty::Schedules>
+  #   * 'schedules'<~Array>
+  #     * <~Pagerduty::Schedules::Schedule>
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'time_zone'<~String>
+  #       * 'today'<~String>
+  #       * 'escalation_policies'<~Array>
+  #         * <~EscalationPolicy>
+  #           * 'id'<~String>
+  #           * 'name'<~String>
+  #           * 'description'<~String>
+  #           * 'escalation_rules'<~Array>
+  #           * 'services'<~Set>
+  #           * 'num_loops'<~Integer>
+  # * 'limit'<~Integer>
+  # * 'offset'<~Integer>
+  # * 'total'<~Integer>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/schedules/list]
   def get_schedules(options={})
-    Pagerduty::Schedules.new(JSON.parse(curl({
+    Pagerduty::Schedules.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/schedules",
       params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # Show detailed information about a schedule, including entries for each layer and sub-schedule
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'since'<~String> - The start of the date range over which you want to return on-call schedule entries and on-call schedule layers
+  #   * 'until'<~String> - The end of the date range over which you want to return schedule entries and on-call schedule layers
+  #   * 'time_zone'<~TimeZone> - Time zone in which dates in the result will be rendered. Defaults to account time zone
+  #
+  # ==== Returns
+  # * response<~ScheduleInfo>:
+  #   * 'id'<~String>
+  #   * 'name'<~String>
+  #   * 'time_zone'<~String>
+  #   * 'today'<~String>
+  #   * 'escalation_policies'<~Array>:
+  #     * <~EscalationPolicy>:
+  #       * 'id'<~String>
+  #       * 'name'<~String>
+  #       * 'description'<~String>
+  #       * 'escalation_rules'<~Array>
+  #       * 'services'<~Set>
+  #       * 'num_loops'<~Integer>
+  #   * 'schedule_layers'<~Array>:
+  #     * <~Pagerduty::Schedules::ScheduleLayer>:
+  #       * 'name'<~String>
+  #       * 'rendered_schedule_entries'<~Array>
+  #       * 'id'<~String>
+  #       * 'priority'<~Integer>
+  #       * 'start'<~String>
+  #       * 'end'<~String>
+  #       * 'restriction_type'<~String>
+  #       * 'rotation_virtual_start'<~String>
+  #       * 'rotation_turn_length_seconds'<~Integer>
+  #       * 'users'<~Array>
+  #         * <~Pagerduty::Schedules::ScheduleLayer::User>:
+  #           * 'member_order'<~Integer>
+  #           * 'user'<~Pagerduty::User>:
+  #             * 'id'<~String>
+  #             * 'name'<~String>
+  #             * 'email'<~String>
+  #             * 'time_zone'<~String>
+  #             * 'color'<~String>
+  #             * 'role'<~String>
+  #             * 'avatar_url'<~String>
+  #             * 'user_url'<~String>
+  #             * 'invitation_sent'<~Boolean>
+  #             * 'marketing'<~String>
+  #             * 'marketing_opt_out'<~String>
+  #             * 'type'<~String>
+  #       * 'restrictions'<~Array>
+  #       * 'rendered_coverage_percentage'<~Float>
+  #   * 'overrides_schedule'<~Pagerduty::Schedules::Override>:
+  #     * 'name'<~String>
+  #     * 'rendered_schedule_entries'<~Array>
+  #   * 'final_schedule'<~Pagerduty::Schedules::FinalSchedule>:
+  #     * 'name'<~String>
+  #     * 'rendered_schedule_entries'<~Array>
+  #     * 'rendered_coverage_percentage'<~Float>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/schedules/show]
   def get_schedule(options={})
-    Pagerduty::ScheduleInfo.new(JSON.parse(curl({
+    Pagerduty::ScheduleInfo.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/schedules/#{options[:id]}",
       params: options,
       method: 'GET'
-     }).body)['schedule'])
+     })['schedule'])
   end
 
+  # List all the users on-call in a given schedule for a given time range.
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'since'<~String> - The start of the date range over which you want to return on-call users
+  #   * 'until'<~String> - The end time of the date range over which you want to return on-call users
+  #
+  # ==== Returns
+  # * <~Array>:
+  #   * <~Pagerduty::User>
+  #     * 'id'<~String>
+  #     * 'name'<~String>
+  #     * 'email'<~String>
+  #     * 'time_zone'<~String>
+  #     * 'color'<~String>
+  #     * 'role'<~String>
+  #     * 'avatar_url'<~String>
+  #     * 'user_url'<~String>
+  #     * 'invitation_sent'<~Boolean>
+  #     * 'marketing'<~String>
+  #     * 'marketing_opt_out'<~String>
+  #     * 'type'<~String>
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/schedules/users]
   def get_schedule_users(options={})
-    JSON.parse(curl({
+    Users.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/schedules/#{options[:id]}/users",
       params: options,
       method: 'GET'
-    }).body)['users'].inject([]) { |users, user|
-      users << Pagerduty::User.new(user)
-    }
+    })).users
   end
 
+  # List existing services
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'include'<~Array> - Include extra information in the response. Possible values are escalation_policy (for inline Escalation Policy) and email_filters (for inline Email Filters)
+  #   * 'time_zone'<~TimeZone> - Time zone in which dates in the result will be rendered. Defaults to account default time zone
+  #
+  # ==== Returns
+  # * services<~Array>:
+  #   * <~Pagerduty::Services::Objects::Service>:
+  #     * 'id'<~String>
+  #     * 'name'<~String>
+  #     * 'description'<~String>
+  #     * 'service_url'<~String>
+  #     * 'service_key'<~String>
+  #     * 'auto_resolve_timeout'<~Integer>
+  #     * 'acknowledgement_timeout'<~Integer>
+  #     * 'created_at'<~String>
+  #     * 'status'<~String>
+  #     * 'last_incident_timestamp'<~String>
+  #     * 'email_incident_creation'<~String>
+  #     * 'incident_counts'<~Hash>
+  #       * 'triggered'<~Integer>
+  #       * 'acknowledged'<~Integer>
+  #       * 'resolved'<~Integer>
+  #       * 'total'<~Integer>
+  #     * 'email_filter_mode'<~String>
+  #     * 'type'<~String>
+  #     * 'escalation_policy'<~String>
+  #     * 'email_filters'<~String> - An object containing inline Email Filters. Only present if email_filters is passed as an argument. Note that only generic_email services have Email Filters
+  #     * 'severity_filter'<~String> - Specifies what severity levels will create a new open incident
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/services/list]
   def get_services(options={})
-    Pagerduty::Services.new(JSON.parse(curl({
+    Pagerduty::Services.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/services",
       params: options,
       method: 'GET'
-    }).body))
+    }))
   end
 
+  # Get details about an existing service
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'include'<~Array> - Include extra information in the response. Possible values are escalation_policy (for inline Escalation Policy) and email_filters (for inline Email Filters)
+  #
+  # ==== Returns
+  # * <~Pagerduty::Services::Objects::Service>:
+  #   * 'id'<~String>
+  #   * 'name'<~String>
+  #   * 'description'<~String>
+  #   * 'service_url'<~String>
+  #   * 'service_key'<~String>
+  #   * 'auto_resolve_timeout'<~Integer>
+  #   * 'acknowledgement_timeout'<~Integer>
+  #   * 'created_at'<~String>
+  #   * 'status'<~String>
+  #   * 'last_incident_timestamp'<~String>
+  #   * 'email_incident_creation'<~String>
+  #   * 'incident_counts'<~Hash>
+  #     * 'triggered'<~Integer>
+  #     * 'acknowledged'<~Integer>
+  #     * 'resolved'<~Integer>
+  #     * 'total'<~Integer>
+  #   * 'email_filter_mode'<~String>
+  #   * 'type'<~String>
+  #   * 'escalation_policy'<~String>
+  #   * 'email_filters'<~String> - An object containing inline Email Filters. Only present if email_filters is passed as an argument. Note that only generic_email services have Email Filters
+  #   * 'severity_filter'<~String> - Specifies what severity levels will create a new open incident
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/services/show]
   def get_service(options={})
-    Pagerduty::Services::Objects::Service.new(JSON.parse(curl({
+    Pagerduty::Services::Objects::Service.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/services/#{options[:id]}",
       params: options,
       method: 'GET'
-    }).body)['service'])
+    })['service'])
   end
 
+  # Create a new service
+  #
+  # ==== Parameters
+  # * options<~Hash>:
+  #   * 'name'<~String> - The name of the service
+  #   * 'escalation_policy_id'<~String> - The id of the escalation policy to be used by this service
+  #   * 'type'<~String> - The type of service to create. Can be one of generic_email, generic_events_api, keynote, nagios, pingdom, server_density or sql_monitor
+  #   * 'description'<~String> - A description for your service. 1024 character maximum
+  #   * 'acknowledgement_timeout'<~Integer> - The duration in seconds before an incidents acknowledged in this service become triggered again. (Defaults to 30 minutes)
+  #   * 'auto_resolve_timeout'<~Integer> - The duration in seconds before a triggered incident auto-resolves itself. (Defaults to 4 hours)
+  #   * 'severity_filter'<~String> - Specifies what severity levels will create a new open incident
+  #
+  # ==== Returns
+  # * <~Pagerduty::Services::Objects::Service>:
+  #   * 'id'<~String>
+  #   * 'name'<~String>
+  #   * 'description'<~String>
+  #   * 'service_url'<~String>
+  #   * 'service_key'<~String>
+  #   * 'auto_resolve_timeout'<~Integer>
+  #   * 'acknowledgement_timeout'<~Integer>
+  #   * 'created_at'<~String>
+  #   * 'status'<~String>
+  #   * 'last_incident_timestamp'<~String>
+  #   * 'email_incident_creation'<~String>
+  #   * 'incident_counts'<~Hash>
+  #     * 'triggered'<~Integer>
+  #     * 'acknowledged'<~Integer>
+  #     * 'resolved'<~Integer>
+  #     * 'total'<~Integer>
+  #   * 'email_filter_mode'<~String>
+  #   * 'type'<~String>
+  #   * 'escalation_policy'<~String>
+  #   * 'email_filters'<~String> - An object containing inline Email Filters. Only present if email_filters is passed as an argument. Note that only generic_email services have Email Filters
+  #   * 'severity_filter'<~String> - Specifies what severity levels will create a new open incident
+  #
+  # {Pagerduty API Reference}[http://developer.pagerduty.com/documentation/rest/services/create]
   def create_service(options={})
-    Pagerduty::Services::Objects::Service.new(JSON.parse(curl({
+    Pagerduty::Services::Objects::Service.new(curl({
       uri: "https://#@@subdomain.pagerduty.com/api/v1/services",
       data: { service: options },
       method: 'POST'
-    }).body)['service'])
+    })['service'])
   end
 
 end