zendesk_api 0.1.11 → 0.2.1

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

@@ -0,0 +1,221 @@
+## Topic Comments
+
+### JSON Format
+TopicComments are represented as simple flat JSON objects which have the following keys:
+
+| Name            | Type    | Read-only | Mandatory | Comment
+| --------------- | ------- | --------- | --------- | -------
+| id              | integer | yes       | no        | Automatically assigned upon creation
+| url             | string  | yes       | no        | The API url of this topic comment
+| topic_id        | integer | no        | yes       | The id of the topic this comment was made on
+| user_id         | integer | no        | yes       | The id of the user making the topic comment
+| body            | string  | no        | yes       | The comment body
+| informative     | boolean | no        | no        | If the comment has been flagged as informative
+| attachments     | array   | yes       | no        | Attachments to this comment as [Attachment](attachments.md) objects
+| created_at      | date    | yes       | no        | The time the topic_comment was created
+| updated_at      | date    | yes       | no        | The time of the last update of the topic_comment
+
+#### Example
+```js
+{
+  "id":              35436,
+  "url":             "https://company.zendesk.com/api/v2/topics/118/comments/35436.json",
+  "topic_id":        118,
+  "user_id":         9442,
+  "body":            "I think this is a great topic",
+  "informative":     false,
+  "attachments": [
+    {
+      "id":           498483,
+      "name":         "crash.log",
+      "content_url":  "https://company.zendesk.com/attachments/crash.log",
+      "content_type": "text/plain",
+      "size":         2532,
+      "thumbnails":   []
+    }
+  ]
+  "created_at":      "2009-07-20T22:55:29Z",
+  "updated_at":      "2011-05-05T10:38:52Z"
+}
+```
+
+### List Topic Comments
+`GET /api/v2/topics/{id}/comments.json`
+
+`GET /api/v2/users/{id}/topic_comments.json`
+
+#### Allowed For:
+
+* Admins on non-enterprise accounts
+* Admins and agents will full forum access on enterprise accounts
+* Users in general as permitted by the forum the topic is in
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{id}/comments.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_comments": [
+    {
+      "id":              35436,
+      "topic_id":        118,
+      "user_id":         9442,
+      "body":            "I think this is a great topic",
+      "informative":     false,
+      "attachments":     []
+      "created_at":      "2012-02-20T22:55:29Z",
+      "updated_at":      "2012-03-05T10:38:52Z"
+    },
+    {
+      "id":              54438,
+      "topic_id":        118,
+      "user_id":         1423,
+      "body":            "This topic is not quite for me",
+      "informative":     true,
+      "attachments":     []
+      "created_at":      "2012-03-20T22:55:29Z",
+      "updated_at":      "2012-03-20T22:55:29Z"
+    }
+  ]
+}
+```
+
+### Show Topic Comment
+`GET /api/v2/topics/{topic_id}/comments/{id}.json`
+
+`GET /api/v2/users/{user_id}/topic_comments/{id}.json`
+
+#### Allowed For
+
+* Admins on non-enterprise accounts
+* Admins and agents will full forum access on enterprise accounts
+* Users in general as permitted by the forum the topic is in
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{topic_id}/comments/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_comment": {
+    "id":              35436,
+    "topic_id":        118,
+    "user_id":         9442,
+    "body":            "I think this is a great topic",
+    "informative":     false,
+    "attachments":     []
+    "created_at":      "2012-02-20T22:55:29Z",
+    "updated_at":      "2012-03-05T10:38:52Z"
+  }
+}
+```
+
+### Create Topic Comment
+`POST /api/v2/topics/{id}/comments.json`
+
+#### Allowed For
+
+* Users in general as permitted by the forum the topic is in
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{id}/comments.json \
+  -H "Content-Type: application/json" -d '{"topic_comment": {"body": "A man walks into a bar"}}' \
+  -v -u {email_address}:{password} -X POST
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/topics/{topic_id}/comments/{id}.json
+
+{
+  "topic_comment": {
+    "id":              35436,
+    "topic_id":        118,
+    "user_id":         9442,
+    "body":            "A man walks into a bar",
+    "informative":     false,
+    "attachments":     []
+    "created_at":      "2012-03-05T10:38:52Z",
+    "updated_at":      "2012-03-05T10:38:52Z"
+  }
+}
+```
+
+### Update Topic Comment
+`PUT /api/v2/topics/{topic_id}/comments/{id}.json`
+
+#### Allowed For
+
+These are subject to the current permission settings on the enclosing account
+
+* Admins on non-enterprise accounts
+* Admins and agents will full forum access on enterprise accounts
+* The user who created the original comment
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{topic_id}/comments/{id}.json \
+  -H "Content-Type: application/json" -d '{"topic_comment": {"body": "A woman walks into a bar"}}' \
+  -v -u {email_address}:{password} -X PUT
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_comment": {
+    "id":              35436,
+    "topic_id":        118,
+    "user_id":         9442,
+    "body":            "A woman walks into a bar",
+    "informative":     false,
+    "attachments":     []
+    "created_at":      "2012-03-05T10:38:52Z",
+    "updated_at":      "2012-03-05T12:38:52Z"
+  }
+}
+```
+
+### Delete Topic Comment
+`DELETE /api/v2/topics/{topic_id}/comments/{id}.json`
+
+#### Allowed For
+
+* Admins on non-enterprise accounts
+* Admins and agents will full forum access on enterprise accounts
+* The user who created the original comment
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{topic_id}/comments/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```

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

@@ -0,0 +1,140 @@
+## Topic Subscriptions
+
+### JSON Format
+Topic subscriptions are links between users and topics they subscribe to
+
+| Name            | Type    | Read-only | Mandatory | Comment
+| --------------- | ------- | --------- | --------- | -------
+| id              | integer | yes       | no        | Automatically assigned upon creation
+| topic_id        | integer | no        | yes       | The topic being subscribed to
+| user_id         | integer | no        | yes       | The user subscribed to the forum
+| created_at      | date    | yes       | no        | The time the subscription was created
+
+#### Example
+```js
+{
+  "id":              35436,
+  "url":             "https://company.zendesk.com/api/v2/topic_subscriptions/35436.json",
+  "topic_id":        32,
+  "user_id":         482,
+  "created_at":      "2009-07-20T22:55:29Z"
+}
+```
+
+### List Topic Subscriptions
+`GET /api/v2/topic/{topic_id}/subscriptions.json`
+
+`GET /api/v2/topic_subscriptions.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topic_subscriptions.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_subscriptions": [
+    {
+      "id":              35436,
+      "topic_id":        32,
+      "user_id":         482,
+      "created_at":      "2009-07-20T22:55:29Z"
+    },
+    {
+      "id":              43681,
+      "topic_id":        334,
+      "user_id":         9471,
+      "created_at":      "2011-08-22T21:12:09Z"
+    }
+  ]
+}
+```
+
+### Show Topic Subscription
+`GET /api/v2/topic_subscriptions/{id}.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topic_subscriptions/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_subscription": {
+    "id":              35436,
+    "topic_id":        32,
+    "user_id":         482,
+    "created_at":      "2009-07-20T22:55:29Z"
+  }
+}
+```
+
+### Create Topic Subscription
+`POST /api/v2/topic_subscriptions.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topic_subscriptions.json \
+  -d '{"user_id": 772, "topic_id": 881}' \
+  -v -u {email_address}:{password} -X POST
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_subscription": {
+    "id":              55436,
+    "topic_id":        881,
+    "user_id":         772,
+    "created_at":      "2012-04-20T22:55:29Z"
+  }
+}
+```
+
+### Delete Topic Subscription
+`DELETE /api/v2/topic_subscriptions/{id}.json`
+
+#### Allowed For
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topic_subscriptions/{id}.json \
+  -v -u {email_address}:{password} -X DELETE
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```

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

@@ -0,0 +1,154 @@
+## Topic Votes
+
+### JSON Format
+Topic votes have the following keys:
+
+| Name            | Type    | Read-only | Mandatory | Comment
+| --------------- | ------- | --------- | --------- | -------
+| id              | integer | yes       | no        | Automatically assigned when creating a vote
+| user_id         | integer | yes       | yes       | The id of the user who votes on the topic
+| topic_id        | integer | yes       | yes       | The id of the topic voted on
+| created_at      | date    | yes       | no        | The time the vote was cast
+
+#### Example
+```js
+{
+  "id":              35436,
+  "user_id":         135,
+  "topic_id":        559,
+  "created_at":      "2011-07-20T22:55:29Z"
+}
+```
+
+### List Topic Votes
+
+Allows agents to see votes cast on a topic or by a specific user.
+
+`GET /api/v2/topics/{id}/votes.json`
+
+`GET /api/v2/users/{id}/topic_votes.json`
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{id}/votes.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "topic_votes": [
+    {
+      "id":              35436,
+      "user_id":         135,
+      "topic_id":        559,
+      "created_at":      "2011-07-20T22:55:29Z"
+    },
+    {
+      "id":              39316,
+      "user_id":         85,
+      "topic_id":        559,
+      "created_at":      "2012-01-10T12:53:42Z"
+    }
+  ]
+}
+```
+
+Agents can pass a `user_id={user_id}` to all actions below to control voting for specific users.
+
+
+### Check for Vote
+`GET /api/v2/topics/{id}/vote.json`
+
+#### Allowed For
+
+ * Anyone who is logged in
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{id}/vote.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+If the current user has not cast a vote in the topic
+
+```http
+Status: 404 Not Found
+```
+
+If the current user has cast a vote in the topic
+
+```http
+Status: 200 OK
+
+{
+  "topic_vote": {
+    "id":              35436,
+    "user_id":         135,
+    "topic_id":        559,
+    "created_at":      "2011-07-20T22:55:29Z"
+  }
+}
+```
+
+### Create Vote
+`POST /api/v2/topics/{id}/vote.json`
+
+#### Allowed For
+
+ * Any logged in user who has not already cast a vote in the given topic
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{id}/vote.json \
+  -H "Content-Type: application/json" -X POST -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+Location: https://{subdomain}.zendesk.com/api/v2/topics/{id}.json
+
+{
+  "topic_vote": {
+    "id":              35436,
+    "user_id":         135,
+    "topic_id":        559,
+    "created_at":      "2012-03-20T22:55:29Z"
+  }
+}
+```
+
+### Delete Vote
+`DELETE /api/v2/topics/{id}/vote.json`
+
+#### Allowed For
+
+ * The user who cast the vote
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/topics/{id}/vote.json \
+  -H "Content-Type: application/json" -X DELETE -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+```