zendesk_api 0.2.6 → 0.3.0

data/lib/zendesk_api/console/extensions.rb

@@ -1,6 +1,10 @@
 class ZendeskAPI::FormatError < ArgumentError; end
 
-class ZendeskAPI::Collection
+module Console
+  def self.included(klass)
+    klass.instance_eval { alias :orig_log_error :log_error }
+  end
+
   def /(id)
     if id == ZendeskAPI::Console::ZD_DIRUP
       if @collection_path.length == 1
@@ -20,8 +24,6 @@ class ZendeskAPI::Collection
     end
   end
 
-  alias :orig_log_error :log_error
-
   def log_error(e, _)
     raise e
   end
@@ -39,7 +41,13 @@ class ZendeskAPI::Collection
   end
 end
 
-class ZendeskAPI::Client
+ZendeskAPI::Collection.send(:include, Console)
+
+module Subclasses
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
   GET_SUBCLASSES = lambda do |ary|
     ary.map! do |klass|
       if klass.name =~ /Resource$/
@@ -56,16 +64,6 @@ class ZendeskAPI::Client
     "/"
   end
 
-  def self.resources
-    @resources ||= begin
-      subclasses = GET_SUBCLASSES.call(ZendeskAPI::Data.subclasses)
-      subclasses.delete_if do |resource|
-        resource.name =~ /ZendeskAPI(::.*){2,}/
-      end
-      subclasses.sort_by(&:resource_name)
-    end
-  end
-
   def to_a
     self.class.resources
   end
@@ -73,9 +71,23 @@ class ZendeskAPI::Client
   def format_headers
     ["resource name"]
   end
+
+  module ClassMethods
+    def resources
+      @resources ||= begin
+        subclasses = GET_SUBCLASSES.call(ZendeskAPI::Data.subclasses)
+        subclasses.delete_if do |resource|
+          resource.name =~ /ZendeskAPI(::.*){2,}/
+        end
+        subclasses.sort_by(&:resource_name)
+      end
+    end
+  end
 end
 
-class ZendeskAPI::Data
+ZendeskAPI::Client.send(:include, Subclasses)
+
+module Path
   def /(method)
     if method == ZendeskAPI::Console::ZD_DIRUP
       if association.options.parent
@@ -89,27 +101,34 @@ class ZendeskAPI::Data
       send(method)
     end
   end
+end
 
-  class << self
-    attr_accessor :format_headers
+module Format
+  def self.extended(klass)
+    class << klass
+      attr_accessor :format_headers
+    end
+  end
 
-    def format(client = nil, &block)
-      if block_given?
-        class_eval do
-          define_method :format do
-            instance_eval &block
-          end
+  def format(client = nil, &block)
+    if block_given?
+      class_eval do
+        define_method :format do
+          instance_eval &block
         end
-      elsif client && client.send(resource_name).loaded?
-        ["@#{resource_name}"]
-      else
-        [resource_name]
       end
+    elsif client && client.send(resource_name).loaded?
+      ["@#{resource_name}"]
+    else
+      [resource_name]
     end
   end
 end
 
-class ZendeskAPI::DataResource
+ZendeskAPI::Data.send(:include, Path)
+ZendeskAPI::Data.extend Format
+
+ZendeskAPI::DataResource.instance_eval do
   format_headers = %w{id created_at}
 
   format do

data/lib/zendesk_api/server/base.rb

@@ -60,6 +60,10 @@ module ZendeskAPI
         register Sinatra::Reloader
       end
 
+      configure :production do
+        require 'newrelic_rpm'
+      end
+
       get '/' do
         haml :index, :format => :html5
       end

data/lib/zendesk_api/server/docs/account_settings.md

@@ -76,6 +76,11 @@ Account Settings are read-only. They contain settings for the various aspects of
 | ---------------------------------- | ------- | -------
 | enabled                            | boolean | GoodData Advanced Analytics is enabled
 
+### Billing
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| backend                            | string  | Backend Billing system either 'internal' or 'zuora'
 
 #### Example
 
@@ -119,6 +124,9 @@ Account Settings are read-only. They contain settings for the various aspects of
   "users": {
     "tagging":true
   }
+  "billing" :{
+     "backend": 'internal'
+   }
 }
 ```
 

data/lib/zendesk_api/server/docs/automations.md

@@ -1,5 +1,11 @@
 ## Automations
 
+An automation consists of one or more actions that are performed if certain conditions are met after a period of time. The conditions are checked every hour. For example, an automation can notify an agent when a ticket remains unresolved after 24 hours.
+
+Even if the actions are performed once, they'll be performed again later if the conditions still apply. To ensure the actions are performed only once, include an action in the automation that cancels one of the conditions.
+
+For more information, see [Streamlining workflow with time-based events and automations](https://support.zendesk.com/entries/20012032).
+
 ### JSON Format
 Automations are represented as simple flat JSON objects which have the following keys.
 

data/lib/zendesk_api/server/docs/changes_roadmap.md

@@ -161,7 +161,7 @@ Furthermore, we have consolidated the grouping and sorting definitions of each V
         {
           "id": 336767,
           "title": "About"
-    	}
+        }
       ]
     }
     ...
@@ -208,4 +208,79 @@ will be changed to
     ...
   }
 }
+```
+
+### April 24, 2013
+
+The following changes will go into effect on April 24, 2013:
+
+#### Moving miscellaneous side-loads into the resource itself
+
+##### Affected endpoints
+
+* ``GET /api/v2/tickets.json``
+* ``GET /api/v2/tickets/{id}.json``
+* ``GET /api/v2/organizations.json``
+* ``GET /api/v2/organizations/{id}.json``
+* ``GET /api/v2/users.json``
+* ``GET /api/v2/users/{id}.json``
+
+##### Deprecation
+
+On January 28, 2012, in the above endpoints, the following side-loaded resources were added
+to the actual model and the root-level side-load was deprecated.
+
+Tickets: last_audits, metric_sets
+Organizations: abilities
+Users: abilities
+
+##### What's changing
+
+To improve consistencies in our API, we are moving some side-loads that are unbounded and never
+duplicated into the actual model instead of at the root level.
+
+##### Example
+
+```
+GET /api/v2/users.json?include=abilities
+
+{
+  "users": [{
+    "id": 1,
+    ...
+  },
+  {
+    "id": 2,
+    ...
+  }],
+  "abilities": [{
+    "user_id": 1,
+    ...
+  },
+  {
+    "user_id": 2,
+    ...
+  }]
+}
+```
+
+will now return
+
+```
+{
+  "users": [{
+    "id": 1,
+    "abilities": {
+      "user_id": 1,
+      ...
+    }
+  },
+  {
+    "id": 2,
+    "abilities": {
+      "user_id": 2,
+      ...
+    }
+  }]
+}
 ```

data/lib/zendesk_api/server/docs/forum_subscriptions.md

@@ -99,8 +99,8 @@ Status: 200 OK
 
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/forum_subscriptions.json \
-  -d '{"user_id": 772, "forum_id": 881}' \
-  -v -u {email_address}:{password} -X POST
+  -d '{"forum_subscription": {"user_id": 772, "forum_id": 881}}' \
+  -v -u {email_address}:{password} -H "Content-Type: application/json" -X POST
 ```
 
 #### Example Response

data/lib/zendesk_api/server/docs/introduction.md

@@ -13,7 +13,7 @@ We reserves the right to add new attributes and resources to the API without adv
 
 ### Security and Authentication
 
-This API is an SSL-only API, regardless of how you may have your account configured. You can authorize against the API using either basic authentication with your username and password credentials or your username and API token.  This token is configurable in your Zendesk account under **Settings** > **Channels** > **API**.
+This API is an SSL-only API, regardless of how you may have your account configured. You can authorize against the API using either basic authentication with your username and password credentials, or with a username and API token.  This token is configurable in your Zendesk account under **Settings** > **Channels** > **API**.
 
 ### Rate Limiting
 
@@ -84,7 +84,7 @@ Collections return a maximum of 100 records per page, and by default return 100
   "users": [ ... ],
   "count": 1234,
   "next_page": "https://account.zendesk.com/api/v2/users.json?page=2",
-  "prev_page": null
+  "previous_page": null
 }
 ```
 
@@ -140,6 +140,7 @@ The response receieved will then include a top-level array of associated data un
 | [Tickets](tickets.html)                                   | users, groups, organizations, last_audits, metric_sets, sharing_agreements
 | [Audits](audits.html)                                     | users, organizations, groups, tickets
 | [Users](users.html)                                       | organizations, abilities, roles, identities, groups
+| [Groups](groups.html)                                     | users
 | [Group Memberships](group_memberships.html)               | users, groups
 | [Organizations](organizations.html)                       | abilities
 | [View Execution / Previewing](views.html#executing-views) | The following are automatically side-loaded if applicable: group, organization, users
@@ -156,6 +157,7 @@ The response receieved will then include a top-level array of associated data un
 
 ### API Clients from the Zendesk Developer Community
 
+* [Python Client Library by Eventbrite](https://github.com/eventbrite/zendesk)
 * [.NET Client Library by Eric Neifert](https://github.com/eneifert/ZendeskApi_v2)
 * [zendeskR by Basho Technologies (R)](https://github.com/tcash21/zendeskR)
 * [node-zendesk by Farrin Reid (node.js)](https://github.com/blakmatrix/node-zendesk)

data/lib/zendesk_api/server/docs/macros.md

@@ -1,5 +1,7 @@
 ## Macros
 
+A macro consists of one or more actions that modify the values of a ticket's fields. Macros are applied to tickets manually by agents. For example, you can create macros for support requests that agents can answer with a single, standard response. For more information, see [Using macros to update and add comments to tickets](https://support.zendesk.com/entries/20011363).
+
 ### JSON Format
 Macros are represented as simple flat JSON objects which have the following keys.
 

data/lib/zendesk_api/server/docs/organizations.md

@@ -180,14 +180,13 @@ Location: https://{subdomain}.zendesk.com/api/v2/organizations/{id}.json
 
 #### Allowed For
 
- * Admins
+ * Agents, restrictions apply on certain actions
 
 #### Using curl
 
 ```bash
-curl https://{subdomain}.zendesk.com/api/v2/organizations/create_many.json \
-  -H "Content-Type: application/json" -X POST -d "{\"organizations\":[{\"name\":\"My Org 1\"}, {\"name\":\"My Org 2\"}]}"
-  -v -u {email_address}:{password}
+curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/organizations/create_many.json \
+  -H "Content-Type: application/json" -X POST -d '{"organizations": [{"name": "Org1"}, {"name": "Org2"}]}'
 ```
 
 #### Example Response

data/lib/zendesk_api/server/docs/requests.md

@@ -1,6 +1,20 @@
 ## Requests
 
-A request is an end-users perspective on a ticket, this API end point is thus for end-users to view, update and create tickets they have access to. End-users can only see public comments and certain fields of a ticket, and you should use the API token to impersonate an end-user when using this end point.
+A _request_ is an end-user's perspective on a ticket. End-users can only see public comments and certain fields of a ticket. Use this API to let end-users view, update, and create tickets they have access to.
+
+####Authentication
+
+You must use the following authentication credentials with this API:
+* Use the end-user's email address, _not_ an agent's email address as is the case with all other API end-points.
+* Use your API token as the password, and append `/token` to the email address.
+
+To get your API token, go to Manage > Channels in Zendesk, and then click the Edit link in the API channel.
+
+__Example__
+
+```js
+-u joe_enduser@zendesk.com/token:{YOUR_API_TOKEN}
+```
 
 ### JSON Format
 Requests are represented as JSON objects which have the following keys:
@@ -89,7 +103,7 @@ Ticket comments have the following keys:
 
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/requests.json \
-  -v -u {email_address}:{password}
+  -v -u {email_address}/token:{api_token}
 ```
 
 #### Example Response
@@ -125,7 +139,7 @@ Status: 200 OK
 
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/requests/{id}.json \
-  -v -u {email_address}:{password}
+  -v -u {email_address}/token:{api_token}
 ```
 
 #### Example Response
@@ -154,7 +168,7 @@ Status: 200 OK
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/requests.json \
   -d '{"request": {"subject": "Help!", "comment": {"body": "My printer is on fire!", "uploads": [...]}}}' \
-  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json"
+  -v -u {email_address}/token:{api_token} -X POST -H "Content-Type: application/json"
 ```
 
 #### Example Response
@@ -185,7 +199,7 @@ Location: https://{subdomain}.zendesk.com/api/v2/requests/{id}.json
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/requests/{id}.json \
   -d '{"request": {"comment": {"body": "Thanks!"}}}' \
-  -v -u {email_address}:{password} -X PUT -H "Content-Type: application/json"
+  -v -u {email_address}/token:{api_token} -X PUT -H "Content-Type: application/json"
 ```
 
 #### Example Response
@@ -213,7 +227,7 @@ Status: 200 OK
 
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/requests/{id}/comments.json \
-  -v -u {email_address}:{password}
+  -v -u {email_address}/token:{api_token}
 ```
 
 #### Example Response
@@ -243,7 +257,7 @@ Status: 200 OK
 
 ```bash
 curl https://{subdomain}.zendesk.com/api/v2/requests/{request_id}/comments/{id}.json \
-  -v -u {email_address}:{password}
+  -v -u {email_address}/token:{api_token}
 ```
 
 #### Example Response

data/lib/zendesk_api/server/docs/tickets.md

@@ -234,6 +234,39 @@ Location: https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json
 }
 ```
 
+#### Request parameters
+
+The POST request takes one parameter, a `ticket` object that lists the values to set when the ticket is created.
+
+| Name                   | Description                                          |
+| --------               | ---------------------------------------------------- |
+| subject                | Required. The subject of the ticket. |
+| comment                | Required. A comment object that describes the problem, incident, question, or task. See [Ticket comments](http://developer.zendesk.com/documentation/rest_api/ticket_audits.html#audit-events) in Audit Events. |
+| requester\_id          | The numeric ID of the user asking for support through the ticket. |
+| submitter\_id          | The numeric ID of the user submitting the ticket. |
+| assignee\_id           | The numeric ID of the agent to assign the ticket to. |
+| group\_id              | The numeric ID of the group to assign the ticket to. |
+| collaborator\_ids      | An array of the numeric IDs of agents or end-users to CC on the ticket. An email notification is sent to them when the ticket is created. |
+| type                   | Allowed values are `problem`, `incident`, `question`, or `task`. |
+| priority               | Allowed values are `urgent`, `high`, `normal`, or `low`. |
+| status                 | Allowed values are `new`, `open`, `pending`, `hold`, `solved` or `closed`. Is set to `open` if status is not specified. |
+| tags                   | An array of tags to add to the ticket. |
+| external\_id           | A unique external ID to link Zendesk tickets to local records. |
+| forum\_topic\_id       | The numeric ID of the topic the ticket originated from, if any. |
+| problem\_id            | For tickets of type "incident", the numeric ID of the problem the incident is linked to, if any. |
+| due\_at                | For tickets of type "task", the due date of the task. Accepts the ISO 8601 date format (yyyy-mm-dd). |
+| custom\_fields         | An array of the custom fields of the ticket. |
+
+#### Example request
+
+```js
+"ticket":{
+ "subject":"My printer is on fire!",
+ "comment": { "body": "The smoke is very colorful." },
+ "priority": "urgent"
+}
+```
+
 ### Updating Tickets
 `PUT /api/v2/tickets/{id}.json`
 
@@ -241,14 +274,6 @@ Location: https://{subdomain}.zendesk.com/api/v2/tickets/{id}.json
 
  * Agents
 
-#### Example Request
-
-```js
-"ticket": {
-  "status": "solved"
-}
-```
-
 #### Using curl
 
 ```bash
@@ -278,6 +303,37 @@ Status: 200 OK
 }
 ```
 
+#### Request parameters
+
+The PUT request takes one parameter, a `ticket` object that lists the values to update. All properties are optional.
+
+| Name                   | Description                                          |
+| --------               | ---------------------------------------------------- |
+| subject                | The subject of the ticket. |
+| comment                | An object that adds a comment to the ticket. See [Ticket comments](http://developer.zendesk.com/documentation/rest_api/ticket_audits.html#audit-events) in Audit Events. |
+| requester\_id          | The numeric ID of the user asking for support through the ticket. |
+| assignee\_id           | The numeric ID of the agent to assign the ticket to. |
+| group\_id              | The numeric ID of the group to assign the ticket to. |
+| collaborator\_ids      | An array of the numeric IDs of agents or end-users to CC. Note that this replaces any existing collaborators. An email notification is sent to them when the ticket is created. |
+| type                   | Allowed values are `problem`, `incident`, `question`, or `task`. |
+| priority               | Allowed values are `urgent`, `high`, `normal`, or `low`. |
+| status                 | Allowed values are `open`, `pending`, `hold`, `solved` or `closed`. |
+| tags                   | An array of tags to add to the ticket. Note that the tags replace any existing tags. |
+| external\_id           | A unique external ID to link Zendesk tickets to local records. |
+| forum\_topic\_id       | The numeric ID of the topic the ticket originated from, if any. |
+| problem\_id            | For tickets of type "incident", the numeric ID of the problem the incident is linked to, if any. |
+| due\_at                | For tickets of type "task", the due date of the task. Accepts the ISO 8601 date format (yyyy-mm-dd). |
+| custom\_fields         | An array of the custom field objects consisting of ids and values. Any tags defined with the custom field replace existing tags.  |
+
+#### Example request
+
+```js
+"ticket": {
+ "comment":{ "body": "Thanks for choosing Acme Jet Motors.", "public":"true" },
+ "status": "solved"
+}
+```
+
 ### Bulk Updating Tickets
 `PUT /api/v2/tickets/update_many.json?ids={ids}`