Podling API Documentation

Conversation

A Conversation has one or more posts, and exactly one original post. The original post is the what 'kicks off' the conversation, and the content is provided on creation of the conversation.

Subresources: Posts

Hiding conversations

A Conversation may be hidden or unhidden via the PATCH endpoint. Hidden conversations will not be listed by other API actions.

Muting conversations

Each user may individually mute any conversation in any group in which they are a member. The user will no longer receive email notifications regarding activity in muted conversations.

Creating Conversations

Example: Creating Conversations with a valid OAuth user as a Group member can be created with attachments.

Request
POST /api/v1/groups/1527-group-14/conversations HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken10
Content-Type: application/json; charset=utf-8

{
  "content": "Conversation!",
  "attachments": [
    {
      "filename": "test.png",
      "url": "http://example.org"
    },
    {
      "filename": "test.gif",
      "url": "http://example.com"
    }
  ]
}
Reponse
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
ETag: "0cf814cb01071b8d1170fb1e68132aff"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 1557

{
  "id": 1444,
  "created_at": "2013-02-28T07:19:14Z",
  "updated_at": "2013-02-28T07:19:14Z",
  "bumped_at": "2013-02-28T07:19:14Z",
  "posts": [
    {
      "id": 1274,
      "content": "Conversation!",
      "content_html": "<p>Conversation!</p>",
      "is_original": true,
      "in_reply_to_id": null,
      "created_at": "2013-02-28T07:19:14Z",
      "updated_at": "2013-02-28T07:19:14Z",
      "attachments": [
        {
          "url": "http://example.org",
          "thumbnail_url": null,
          "filename": "test.png",
          "mimetype": null,
          "size": null,
          "security": {
            "signature": "d49e1179402cc58c1da495f1ab95d9f17866eee4f7360fdc6a6e56cdabc7bb8e",
            "policy": "eyJoYW5kbGUiOiJleGFtcGxlLm9yZyIsImNhbGwiOlsicmVhZCIsImNvbnZlcnQiLCJwaWNrIl0sImV4cGlyeSI6MTM2MjEyMjM1NH0="
          },
          "thumbnail_security": {
            "signature": "17cc7503319ad2b98141b1eb9cefc611c771c20d8685ea4ba6f5145c9ccaef7a",
            "policy": "eyJjYWxsIjpbInJlYWQiLCJjb252ZXJ0IiwicGljayJdLCJleHBpcnkiOjEzNjIxMjIzNTR9"
          }
        },
        {
          "url": "http://example.com",
          "thumbnail_url": null,
          "filename": "test.gif",
          "mimetype": null,
          "size": null,
          "security": {
            "signature": "44697099bc2bc41f6c79cdb7a64d3915db64d3481f5b7595e08df5a566d0f849",
            "policy": "eyJoYW5kbGUiOiJleGFtcGxlLmNvbSIsImNhbGwiOlsicmVhZCIsImNvbnZlcnQiLCJwaWNrIl0sImV4cGlyeSI6MTM2MjEyMjM1NH0="
          },
          "thumbnail_security": {
            "signature": "17cc7503319ad2b98141b1eb9cefc611c771c20d8685ea4ba6f5145c9ccaef7a",
            "policy": "eyJjYWxsIjpbInJlYWQiLCJjb252ZXJ0IiwicGljayJdLCJleHBpcnkiOjEzNjIxMjIzNTR9"
          }
        }
      ],
      "user": {
        "id": 3002,
        "name": "OAuth user",
        "email": "user7@example.org",
        "avatar_url": null,
        "twitter_username": null,
        "profile": null,
        "location": null,
        "created_at": "2013-02-28T07:19:14Z",
        "url": "http://www.example.com/api/v1/users/3002"
      },
      "likes": [

      ]
    }
  ]
}
Back to top

Example: Creating Conversations with a valid OAuth user as a Group member creates a new conversation with an original post.

Request
POST /api/v1/groups/1525-group-12/conversations HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken8
Content-Type: application/json; charset=utf-8

{
  "content": "Conversation!"
}
Reponse
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
ETag: "3cf975cc384801814700464dd8bbd68e"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 570

{
  "id": 1442,
  "created_at": "2013-02-28T07:19:14Z",
  "updated_at": "2013-02-28T07:19:14Z",
  "bumped_at": "2013-02-28T07:19:14Z",
  "posts": [
    {
      "id": 1272,
      "content": "Conversation!",
      "content_html": "<p>Conversation!</p>",
      "is_original": true,
      "in_reply_to_id": null,
      "created_at": "2013-02-28T07:19:14Z",
      "updated_at": "2013-02-28T07:19:14Z",
      "attachments": [

      ],
      "user": {
        "id": 3000,
        "name": "OAuth user",
        "email": "user5@example.org",
        "avatar_url": null,
        "twitter_username": null,
        "profile": null,
        "location": null,
        "created_at": "2013-02-28T07:19:14Z",
        "url": "http://www.example.com/api/v1/users/3000"
      },
      "likes": [

      ]
    }
  ]
}
Back to top

Listing Conversations

Example: Listing Conversations responds with Conversations interleaved from multiple Groups.

Request
GET /api/v1/users/3099/conversations HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken47
Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
ETag: "91f4d02ec3cea516877379eb705f534a"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 2125

[
  {
    "id": 1521,
    "created_at": "2013-02-28T07:19:18Z",
    "updated_at": "2013-02-28T07:19:18Z",
    "bumped_at": "2013-02-28T05:19:18Z",
    "posts": [
      {
        "id": 1314,
        "content": "2 hours",
        "content_html": "<p>2 hours</p>",
        "is_original": true,
        "in_reply_to_id": null,
        "created_at": "2013-02-28T05:19:18Z",
        "updated_at": "2013-02-28T07:19:18Z",
        "attachments": [

        ],
        "user": {
          "id": 3103,
          "name": "User 86",
          "email": "user108@example.org",
          "avatar_url": null,
          "twitter_username": null,
          "profile": null,
          "location": null,
          "created_at": "2013-02-28T07:19:18Z",
          "url": "http://www.example.com/api/v1/users/3103"
        },
        "likes": [

        ]
      }
    ],
    "group": {
      "id": 1568,
      "name": "Group 55",
      "slug": "1568-group-55",
      "created_at": "2013-02-28T07:19:18Z",
      "updated_at": "2013-02-28T07:19:18Z",
      "member_count": 1
    }
  },
  {
    "id": 1520,
    "created_at": "2013-02-28T07:19:18Z",
    "updated_at": "2013-02-28T07:19:18Z",
    "bumped_at": "2013-02-28T04:19:18Z",
    "posts": [
      {
        "id": 1313,
        "content": "3 hours",
        "content_html": "<p>3 hours</p>",
        "is_original": true,
        "in_reply_to_id": null,
        "created_at": "2013-02-28T04:19:18Z",
        "updated_at": "2013-02-28T07:19:18Z",
        "attachments": [

        ],
        "user": {
          "id": 3101,
          "name": "User 84",
          "email": "user106@example.org",
          "avatar_url": null,
          "twitter_username": null,
          "profile": null,
          "location": null,
          "created_at": "2013-02-28T07:19:18Z",
          "url": "http://www.example.com/api/v1/users/3101"
        },
        "likes": [

        ]
      }
    ],
    "group": {
      "id": 1567,
      "name": "Group 54",
      "slug": "1567-group-54",
      "created_at": "2013-02-28T07:19:18Z",
      "updated_at": "2013-02-28T07:19:18Z",
      "member_count": 1
    }
  },
  {
    "id": 1519,
    "created_at": "2013-02-28T07:19:18Z",
    "updated_at": "2013-02-28T07:19:18Z",
    "bumped_at": "2013-02-28T03:19:18Z",
    "posts": [
      {
        "id": 1312,
        "content": "4 hours",
        "content_html": "<p>4 hours</p>",
        "is_original": true,
        "in_reply_to_id": null,
        "created_at": "2013-02-28T03:19:18Z",
        "updated_at": "2013-02-28T07:19:18Z",
        "attachments": [

        ],
        "user": {
          "id": 3098,
          "name": "User 82",
          "email": "user103@example.org",
          "avatar_url": null,
          "twitter_username": null,
          "profile": null,
          "location": null,
          "created_at": "2013-02-28T07:19:18Z",
          "url": "http://www.example.com/api/v1/users/3098"
        },
        "likes": [

        ]
      }
    ],
    "group": {
      "id": 1566,
      "name": "Group 53",
      "slug": "1566-group-53",
      "created_at": "2013-02-28T07:19:18Z",
      "updated_at": "2013-02-28T07:19:18Z",
      "member_count": 1
    }
  }
]
Back to top

Muting conversations

Example: Muting conversations with a valid OAuth user unsubscribes the user from the conversation.

Request
POST /api/v1/groups/1558-group-45/conversations/1497/mute HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken39
Reponse
HTTP/1.1 204 No Content
Cache-Control: no-cache
Back to top

Paginating Conversations

Example: Paginating Conversations with three conversations includes rel=next link header normally.

Request
GET /api/v1/groups/1562-group-49/conversations?limit=2 HTTP/1.1
Host: podling.com
Authorization: Bearer accesstoken43
Reponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Link: <http://www.example.com/api/v1/groups/1562-group-49/conversations?bumped_before=2013-02-28T06%3A19%3A18Z&limit=2>; rel="next"
ETag: "d0de95201a4b468c67fd8de8460b9544"
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 261

[
  {
    "id": 1506,
    "created_at": "2013-02-28T07:19:18Z",
    "updated_at": "2013-02-28T07:19:18Z",
    "bumped_at": "2013-02-28T07:19:18Z",
    "posts": [

    ]
  },
  {
    "id": 1507,
    "created_at": "2013-02-28T06:19:18Z",
    "updated_at": "2013-02-28T07:19:18Z",
    "bumped_at": "2013-02-28T06:19:18Z",
    "posts": [

    ]
  }
]
Back to top