zendesk_api 0.1.11 → 0.2.1

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

@@ -0,0 +1,229 @@
+## Forums
+
+### JSON Format
+Forums are represented with the following attributes:
+
+| Name               | Type    | Read-only | Mandatory | Comment
+| ------------------ | ------- | --------- | --------- | -------
+| id                 | integer | yes       | no        | Automatically assigned upon creation
+| url                | string  | yes       | no        | The API url of this forum
+| name               | string  | no        | yes       | The name of the forum
+| description        | string  | no        | no        | A description of the forum
+| category_id        | integer | no        | no        | Category this forum is in
+| organization_id    | integer | no        | no        | Organization this forum is restricted to
+| locale_id          | integer | no        | no        | User locale id this forum is restricted to
+| locked             | boolean | no        | no        | Whether this forum is locked such that new entries and comments cannot be made
+| unanswered_topics  | integer | yes       | no        | Contains the number of unanswered questions if this forum's topics are questions.
+| position           | integer | no        | no        | The position of this forum relative to other forums in the same category
+| forum_type         | string  | no        | no        | The type of the topics in this forum, valid values: "articles", "ideas" or "questions"
+| access             | string  | no        | no        | Who has access to this forum, valid values: "everybody", "logged-in users" or "agents only"
+| created_at         | date    | yes       | no        | The time the forum was created
+| updated_at         | date    | yes       | no        | The time of the last update of the forum
+
+#### Example
+```js
+{
+  "id":              35436,
+  "url":             "https://company.zendesk.com/api/v2/forums/35436.json",
+  "name":            "FAQs",
+  "description:":    "This forum contains all product FAQs",
+  "category_id":     null,
+  "organization_id": null,
+  "locale_id":       null,
+  "locked":          true,
+  "position":        4,
+  "forum_type":      "articles",
+  "access":          "everybody",
+  "created_at":      "2010-07-20T22:55:29Z",
+  "updated_at":      "2012-03-05T10:38:52Z"
+}
+```
+
+### List Forums
+`GET /api/v2/forums.json`
+
+`GET /api/v2/categories/{id}/forums.json`
+
+#### Allowed For:
+
+ * Anyone on accounts that have at least one publicly accessible forum
+ * End users and agents on accounts that have at least one logged-in user accessible forum
+ * Admins
+
+Only lists the forums available to the inquiring user as per the individual forum settings.
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/forums.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "forums": [
+    {
+      "id":              35436,
+      "name":            "FAQs",
+      "description:":    "This forum contains all product FAQs",
+      "category_id":     null,
+      "organization_id": null,
+      "locale_id":       null,
+      "locked":          true,
+      "position":        4,
+      "forum_type":      "articles",
+      "access":          "everybody",
+      "created_at":      "2010-07-20T22:55:29Z",
+      "updated_at":      "2012-03-05T10:38:52Z"
+    },
+    {
+      "id":              12,
+      ...
+      "created_at":      "2011-07-20T04:31:29Z",
+      "updated_at":      "2012-02-02T10:32:59Z"
+    }
+  ]
+}
+```
+
+### Show Forum
+`GET /api/v2/forums/{id}.json`
+
+#### Allowed For:
+
+ * Anyone with permission to access this specific forum
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/forums/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "forum": {
+    "id":              35436,
+    "name":            "FAQs",
+    "description:":    "This forum contains all product FAQs",
+    "category_id":     null,
+    "organization_id": null,
+    "locale_id":       null,
+    "locked":          true,
+    "position":        4,
+    "forum_type":      "articles",
+    "access":          "everybody",
+    "created_at":      "2010-07-20T22:55:29Z",
+    "updated_at":      "2012-03-05T10:38:52Z"
+  }
+}
+```
+
+### Create Forum
+`POST /api/v2/forums.json`
+
+#### Allowed For
+
+ * Admins on non-enterprise accounts
+ * Admins and agents will full forum access on enterprise accounts
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/forums.json \
+  -H "Content-Type: application/json" -X POST \
+  -d '{"forum": {"name": "My Forum", "forum_type": "articles", "access": "logged-in users" }}' \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/forums/{id}.json
+
+{
+  "forum": {
+    "id":              354882,
+    "name":            "My Forum",
+    "description:":    null,
+    "category_id":     null,
+    "organization_id": null,
+    "locale_id":       null,
+    "locked":          false,
+    "position":        9999,
+    "forum_type":      "articles",
+    "access":          "logged-in users",
+    "created_at":      "2012-03-05T10:38:52Z",
+    "updated_at":      "2012-03-05T10:38:52Z"
+  }
+}
+```
+
+### Update Forum
+`PUT /api/v2/forum/{id}.json`
+
+#### Allowed For
+
+ * Admins on non-enterprise accounts
+ * Admins and agents will full forum access on enterprise accounts
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/forums/{id}.json \
+  -H "Content-Type: application/json" -d '{"forum": {"name": "The Forum"}}' \
+  -v -u {email_address}:{password} -X PUT
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "forum": {
+    "id":              354882,
+    "name":            "The Forum",
+    "description:":    null,
+    "category_id":     null,
+    "organization_id": null,
+    "locale_id":       null,
+    "locked":          false,
+    "position":        9999,
+    "forum_type":      "articles",
+    "access":          "logged-in users",
+    "updated_at":      "2012-03-05T10:38:52Z",
+    "updated_at":      "2012-03-10T04:28:11Z"
+  }
+}
+```
+
+### Delete Forum
+`DELETE /api/v2/forums/{id}.json`
+
+#### Allowed For
+
+ * Admins on non-enterprise accounts
+ * Admins and agents will full forum access on enterprise accounts
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/forums/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```

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

@@ -0,0 +1,229 @@
+## Group Memberships
+
+A membership links an agent to a group. Groups can have many agents, as agents can be in many groups. You can use the API to list what agents are in which groups, and reassign group members.
+
+### JSON Format
+Memberships are simple links between a user and a group
+
+| Name            | Type    | Read-only | Mandatory | Comment
+| --------------- | ------- | --------- | --------- | -------
+| id              | integer | yes       | no        | Automatically assigned upon creation
+| url             | string  | yes       | no        | The API url of this record
+| user_id         | integer | no        | yes       | The id of an agent
+| group_id        | integer | no        | yes       | The id of a group
+| default         | boolean | no        | no        | If true, tickets assigned directly to the agent will assume this membership's group.
+| created_at      | date    | yes       | no        | The time the membership was created
+| updated_at      | date    | yes       | no        | The time of the last update of the membership
+
+#### Example
+```js
+{
+  "id":         4,
+  "user_id":    29,
+  "group_id":   12,
+  "default":    true,
+  "created_at": "2009-05-13T00:07:08Z",
+  "updated_at": "2011-07-22T00:11:12Z"
+}
+```
+
+### List Memberships
+`GET /api/v2/group_memberships.json`
+
+`GET /api/v2/users/{user_id}/group_memberships.json`
+
+`GET /api/v2/groups/{group_id}/memberships.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/group_memberships.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "group_memberships": [
+    {
+      "id":         4,
+      "user_id":    29,
+      "group_id":   12,
+      "default":    true,
+      "created_at": "2009-05-13T00:07:08Z",
+      "updated_at": "2011-07-22T00:11:12Z"
+    },
+    {
+      "id":         49,
+      "user_id":    155,
+      "group_id":   3,
+      "default":    false,
+      "created_at": "2012-03-13T22:01:32Z",
+      "updated_at": "2012-03-13T22:01:32Z"
+    }
+  ]
+}
+```
+
+### List Assignable Memberships
+`GET /api/v2/group_memberships/assignable.json`
+
+`GET /api/v2/groups/{group_id}/memberships/assignable.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/group_memberships/assignable.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "group_memberships": [
+    {
+      "id":         4,
+      "user_id":    29,
+      "group_id":   12,
+      "default":    true,
+      "created_at": "2009-05-13T00:07:08Z",
+      "updated_at": "2011-07-22T00:11:12Z"
+    },
+    {
+      "id":         49,
+      "user_id":    155,
+      "group_id":   3,
+      "default":    false,
+      "created_at": "2012-03-13T22:01:32Z",
+      "updated_at": "2012-03-13T22:01:32Z"
+    }
+  ]
+}
+```
+
+### Show Membership
+`GET /api/v2/group_memberships/{id}.json`
+
+`GET /api/v2/users/{user_id}/group_memberships/{id}.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/group_memberships/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "group_membership": {
+     "id":         4,
+     "user_id":    29,
+     "group_id":   12,
+     "default":    true,
+     "created_at": "2009-05-13T00:07:08Z",
+     "updated_at": "2011-07-22T00:11:12Z"
+  }
+}
+```
+
+### Create Membership
+`POST /api/v2/group_memberships.json`
+
+`POST /api/v2/users/{user_id}/group_memberships.json`
+
+Creating a membership means assigning an agent to a given group
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/group_memberships.json \
+  -X POST -d '{"group_membership": {"user_id": 72, "group_id": 88}}' \
+  -H "Content-Type: application/json" -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/group_memberships/{id}.json
+
+{
+  "group_membership": {
+     "id":         461,
+     "user_id":    72,
+     "group_id":   88,
+     "default":    true,
+     "created_at": "2012-04-03T12:34:01Z",
+     "updated_at": "2012-04-03T12:34:01Z"
+  }
+}
+```
+
+### Delete Membership
+`DELETE /api/v2/group_memberships/{id}.json`
+
+`DELETE /api/v2/users/{user_id}/group_memberships/{id}.json`
+
+Immediately removes a user from a group and schedules a job to unassign all working tickets
+that are assigned to the given user and group combination
+
+#### Allowed For
+
+ * Admins
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/group_memberships/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```
+
+### Set membership as default
+`PUT /api/v2/users/{user_id}/group_memberships/{id}/make_default.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/group_memberships/{id}/make_default.json \
+  -v -u {email_address}:{password} -X PUT
+```
+
+#### Example Response
+
+Same as List Memberships