zendesk_api 0.1.11 → 0.2.1

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

@@ -0,0 +1,106 @@
+## Search
+
+The search API is a unified search API that returns tickets, users, organizations, and forum topics.  Define filters to narrow your search results according to result type, date attributes, and object attributes such as ticket requester or tag.
+
+### A few example queries
+
+| Search query                                                 | Returns...
+| ------------------------------------------------------------ | ----------
+| status<solved requester:user@domain.com type:ticket          | All unsolved tickets requested by user@domain.com
+| type:user tags:premium_support                               | All users tagged with ``premium_support``
+| created>2012-06-17 type:ticket organization:"Mondocam Photo" | Tickets created within the Mondocam Photo organization after July 17, 2012
+
+Our [search reference](https://support.zendesk.com/entries/20239737-zendesk-search-reference) offers a complete guide to all search filters available for advanced search.
+
+### JSON Format
+Queries are represented as JSON objects which have the following keys.
+
+| Name                  | Type                 | Comment
+| --------------------- | ---------------------| --------------------
+| count                 | integer              | The total number of results matching this query
+| next_page             | string               | URL to the next page of results
+| prev_page             | string               | URL to the previous page of results
+| results               | array                | May consist of Tickets, Users, Groups, Organizations, and Topics.  A ``result_type`` value is added to each result object and can have the following values: ``ticket``, ``user``, ``group``, ``organization``, ``topic``.
+
+#### Example
+```js
+{
+  "count":     1234,
+  "next_page": "https://foo.zendesk.com/api/v2/search.json?query=\"type:Group hello\"&sort_by=created_at&sort_order=desc&page=2",
+  "prev_page": null,
+  "results": [
+    {
+      "name":        "Hello DJs",
+      "created_at":  "2009-05-13T00:07:08Z",
+      "updated_at":  "2011-07-22T00:11:12Z",
+      "id":          211,
+      "result_type": "group"
+      "url":         "https://foo.zendesk.com/api/v2/groups/211.json"
+    },
+    {
+      "name":        "Hello MCs",
+      "created_at":  "2009-08-26T00:07:08Z",
+      "updated_at":  "2010-05-13T00:07:08Z",
+      "id":          122,
+      "result_type": "group"
+      "url":         "https://foo.zendesk.com/api/v2/groups/122.json"
+    }
+    ...
+  ]
+}
+```
+
+### Search
+`GET /api/v2/search.json?query={search term}`
+
+#### Available parameters
+
+| Name                  | Type                | Required  | Comments
+| --------------------- | --------------------| --------- | -------------------
+| query                 | string              | yes       | The search text to be matched. Examples: "carrot potato", "'carrot potato'"
+| sort_by               | string              | no        | Possible values are 'updated_at', 'created_at', 'priority', 'status', and 'ticket_type'
+| sort_order            | string              | no        | One of 'relevance', 'asc', 'desc'. Defaults to 'relevance' when no 'order' criteria is requested.
+
+#### Allowed For:
+
+ * Logged in users
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/search.json?query={search term} \
+  -v -u {email_address}:{password}
+```
+
+### Errors JSON Format
+Errors are represented as JSON objects which have the following keys:
+
+| Name                  | Type                 | Comment
+| --------------------- | ---------------------| --------------------
+| error                 | string               | The type of error. e.g.: 'unavailable', 'invalid'
+| description           | string               |
+
+#### Example
+```js
+{
+  "error": "unavailable",
+  "description": "Sorry, we could not complete your search query. Please try again in a moment."
+}
+```
+
+### Anonymous search
+`GET /api/v2/portal/search.json?query={search term}`
+
+This resource behaves the same as /api/v2/search, but allows anonymous users to search public forums.
+
+#### Allowed For:
+
+ * Logged in users
+ * Anonymous users on public forums
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/portal/search.json?query={search term} \
+  -v -u {email_address}:{password}
+```

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

@@ -0,0 +1,57 @@
+## Sharing Agreements
+
+### JSON Format
+Sharing Agreements have the following format:
+
+| Name            | Type                              | Comment
+| --------------- | --------------------------------- | -------
+| id              | integer                           | Automatically assigned upon creation
+| name            | string                            | Name of this sharing agreement
+| type            | string                            | Can be one of the following: inbound, outbound
+| partner_name    | string                            | Can be one of the following: jira, null
+| status          | string                            | Can be one of the following: accepted, declined, pending, inactive
+| created_at      | date                              | The time the record was created
+
+#### Example
+```js
+{
+  "id":         88335,
+  "url":        "https://company.zendesk.com/api/v2/agreements/88335.json",
+  "name":       "Ticket Sharing",
+  "type":       "inbound",
+  "status":     "accepted",
+  "created_at": "2012-02-20T22:55:29Z"
+}
+```
+
+### List Sharing Agreements
+`GET /api/v2/sharing_agreements.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/sharing_agreements.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "sharing_agreements": [
+    {
+      "id":    1,
+      "name":  "Foo @ Zendesk",
+      "type":  "inbound",
+      ...
+     },
+    ...
+  ]
+}
+```

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

@@ -0,0 +1,125 @@
+## Side-Loading
+### Overview
+Side loading is an API feature that allows you to retrieve related records as part of a single request. For example, consider getting a list of group memberships, your response looks like this:
+
+```js
+{
+  "group_memberships": [
+    {
+      "id":       4,
+      "user_id":  29,
+      "group_id": 12,
+      "created_at": "2009-05-13T00:07:08Z",
+      "updated_at": "2011-07-22T00:11:12Z"
+    },
+    {
+      "id":       49,
+      "user_id":  155,
+      "group_id": 3,
+      "created_at": "2012-03-13T22:01:32Z",
+      "updated_at": "2012-03-13T22:01:32Z"
+    }
+  ]
+}
+```
+
+By allowing side loading of users and groups, this response turns into:
+
+```js
+{
+  "group_memberships": [
+    {
+      "id":       4,
+      "user_id":  29,
+      "group_id": 12,
+      "created_at": "2009-05-13T00:07:08Z",
+      "updated_at": "2011-07-22T00:11:12Z"
+    },
+    {
+      "id":       49,
+      "user_id":  155,
+      "group_id": 3,
+      "created_at": "2012-03-13T22:01:32Z",
+      "updated_at": "2012-03-13T22:01:32Z"
+    }
+  ],
+  "users": [
+    { "id": 29, ... },
+    { "id": 155, ... }
+  ],
+  "groups": [
+    { "id": 12, ... },
+    { "id": 3, ... }
+  ]
+}
+```
+
+Meaning, we now return the full serialized representation of users and groups referred from the primary collection being retrieved. In order to side load resources, all you need to do is to add `include=users,groups` parameter to the HTTP request.
+
+### Special Sideloads
+
+#### Abilities
+
+A resource may have an additional `abilities` sideload which represents the abilities that the current user has on a given resource. For example:
+
+`GET /api/v2/users/me.json?include=abilities`
+
+```js
+{
+  "abilities": [
+    {
+      "can_edit": true,
+      "can_edit_password": true,
+      "can_manage_identities_of": true,
+      "can_verify_identities": false,
+      "url": "http://dev.localhost:3001/api/v2/users/11.json",
+      "user_id": 11
+    }
+  ],
+  "user": {
+    "active": true,
+    "alias": null,
+    "created_at": "2012-05-08T01:04:47Z",
+    "custom_role_id": null,
+    "details": null,
+    "email": "agent@zendesk.com",
+    "external_id": null,
+    "id": 11,
+    "last_login_at": "2012-05-21T21:19:19Z",
+    "locale_id": null,
+    "moderator": true,
+    "name": "Agent Extraordinaire",
+    "notes": null,
+    "only_private_comments": false,
+    "organization_id": 11,
+    "phone": null,
+    "photo": null,
+    "role": "admin",
+    "shared": false,
+    "signature": null,
+    "suspended": false,
+    "tags": [],
+    "ticket_restriction": null,
+    "time_zone": "Pacific Time (US & Canada)",
+    "updated_at": "2012-05-08T01:04:47Z",
+    "url": "http://dev.localhost:3001/api/v2/users/11.json",
+    "verified": true
+  }
+}
+```
+
+### Supported End Points
+
+Currently the below end points support side loading. You can side load a single type of resource, or given in the examples.
+
+  * `/api/v2/organizations.json?include=users,groups`
+  * `/api/v2/tickets/123/audits.json?include=users,organizations,groups,tickets`
+  * `/api/v2/tickets/123.json?include=users,organizations,groups`
+  * `/api/v2/users/123.json?include=organizations,abilities,custom_roles`
+  * `/api/v2/memberships.json?include=users,groups`
+  * `/api/v2/topics.json?include=users,forums`
+  * `/api/v2/forums/123/topics.json?include=users`
+  * `/api/v2/users/123/topics.json?include=users`
+  * `/api/v2/topic_comments.json?include=users`
+  * `/api/v2/topics/123/comments.json?include=users`
+  * `/api/v2/users/123/topic_comments.json?include=users`

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

@@ -0,0 +1,182 @@
+## Suspended Tickets
+
+
+| Name             | Type                   | Read-only | Mandatory | Comment
+| ---------------- | ---------------------- | --------- | --------- | -------
+| id               | integer                | yes       | no        | Automatically assigned
+| url              | string                 | yes       | no        | The API url of this ticket
+| author           | object                 | yes       | no        | The author id (if available), name and email
+| subject          | string                 | yes       | no        | The value of the subject field for this ticket
+| content          | string                 | yes       | no        | The content that was flagged
+| cause            | string                 | yes       | no        | Why the ticket was suspended
+| message_id       | string                 | yes       | no        | The id of the email, if available
+| created_at       | date                   | yes       | no        | When this record was created
+| updated_at       | date                   | yes       | no        | When this record last got updated
+| via              | [Via](#the-via-object) | yes       | no        | This object explains how the ticket was created
+
+#### Example
+```js
+{
+  "id":               435,
+  "url":              "https://example.zendesk.com/api/v2/tickets/35436.json",
+  "author":           { "id": 1, "name": "Mr. Roboto", "email": "styx@example.com" },
+  "subject":          "Help, my printer is on fire!",
+  "content":          "Out Of Office Reply",
+  "cause":            "Detected as spam",
+  "created_at":       "2009-07-20T22:55:29Z",
+  "updated_at":       "2011-05-05T10:38:52Z",
+  "via": {
+    "channel": "web"
+  }
+}
+```
+
+### Listing Suspended Tickets
+`GET /api/v2/suspended_tickets.json`
+
+#### Allowed For
+
+ * Unrestricted Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/suspended_tickets.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+```http
+Status: 200 OK
+
+{
+  "suspended_tickets": [
+    {
+      "id":      3436,
+      "subject": "Help I need somebody!",
+      "cause":   "Detected as spam",
+      ...
+    },
+    {
+      "id":      207623,
+      "subject": "Not just anybody!",
+      "cause":   "Automated response mail",
+      ...
+    },
+  ]
+}
+```
+
+### Getting Suspended Tickets
+`GET /api/v2/suspended_tickets/{id}.json`
+
+#### Allowed For
+
+ * Unrestricted Agents
+
+#### Using curl:
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/suspended_tickets/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "suspended_ticket": {
+    {
+      "id":      35436,
+      "subject": "My printer is on fire!",
+      "cause":   "Automated response mail",
+      ...
+    }
+  }
+}
+```
+
+### Recovering Suspended Tickets
+`PUT /api/v2/suspended_tickets/{id}/recover.json`
+
+#### Allowed For
+
+ * Unrestricted Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/suspended_tickets/{id}/recover.json \
+  -X PUT -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```
+
+### Recovering Multiple Suspended Tickets
+`PUT /api/v2/suspended_tickets/recover_many.json?ids={id1},{id2}`
+
+Note: Suspended tickets that fail to be recovered will be included in the response.
+
+#### Allowed For
+
+ * Unrestricted Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/suspended_tickets/recover_many.json?ids={id1},{id2} \
+  -H "Content-Type: application/json" -X PUT \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```
+
+### Deleting Tickets
+`DELETE /api/v2/suspended_tickets/{id}.json`
+
+#### Allowed For
+
+ * Unrestricted Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/suspended_tickets/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```
+
+### Deleting Multiple Tickets
+`DELETE /api/v2/suspended_tickets/destroy_many.json?ids={id1},{id2}`
+
+#### Allowed For
+
+ * Unrestricted Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/suspended_tickets/destroy_many.json?ids={id1},{id2} \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```