Introduction

In general, the REST API is optimised for mobile app development.

You can also try:

XMPP-FTW, which is better for realtime web application programming. Refer to their docs for more information.

Buddycloud HTTP REST API

Welcome to the Buddycloud REST API documentation.

The listed REST API calls give you access to the entire Buddycloud stack. These API calls are designed to make it easy to add rich in-app messaging and social features to your web or mobile app.

Getting Help

We really want this API to be useful to you. If you run into problems please contact us. Documentation fixes and ideas for improvements are always welcome.

These pages are generated using Slate.

REST API Conventions

Encoding

The REST API uses UTF-8 character encoding. Request headers should include a Content-Type of application/json; charset=utf-8.

Authentication

The REST API uses HTTP basic authentication. The username should also include the user’s domain (e.g. username@example.com).

External Authentication

Buddycloud’s backend enables you to authenticate your users against your own site by forwarding login requests to your own API. Email us to have this feature enabled for your domain.

Time Format

All timestamps are ISO-8601 formatted.

Discovery

Applications shall work with hardcoded API endpoints but, if need be, there’s a way to discover the REST API endpoint for a given Buddycloud domain.

REST API Discovery

Problem: Your application is designed for users on multiple Buddycloud sites each with their own REST API. It is necessary to discover the API endpoint for each user’s domain.

• juliet@capulet.lit connects to the Capulet Buddycloud API using https://buddycloud.capulet.lit/api

• romeo@montague.lit connects to the Montague Buddycloud API using https://montague.lit/buddycloud/api

Solution: Buddycloud solves this by using a DNS lookup to discover the REST API endpoint.

Example

In order to resolve the API endpoint for buddycloud.com, do:

dig txt +short _buddycloud-api._tcp.buddycloud.com

You shall get a TXT record such as the following as response:

"v=1.0" "host=buddycloud.com" "protocol=https" "path=/api" "port=443"

Which means the API endpoint for buddycloud.com is:

https://buddycloud.com:443/api

To find the API for a user’s domain:

• Clients query for the TXT record of _buddycloud-api._tcp.<user's domain>.
• The results return an IANA service record with the information below

API TXT record information

The following API endpoint reflects the above response: https://buddycloud.com:443/api-endpoint.

Accounts

Your users will need to authenticate against the server with a username that looks like username@domain. For example username@example.buddycloud.com.

Create User

POST /api/account

Example

Creating the juliet@buddycloud.com account using curl:

curl https://buddycloud.com/api/account \
     -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{ \
            "username": "juliet@buddycloud.com", \
            "password": "romeo-forever", \
            "email": "juliet@buddycloud.com" \
         }'

This will create a new account for username and set their password and email. The email is used for password resets and for optional alerts from the push notification system.

Payload Parameters

Check User Credentials

GET /api/

Example

Checking if juliet@buddycloud.com matches with password romeo-forever, using curl:

curl https://buddycloud.com/api/ \
    -X GET \
    -u juliet@buddycloud.com:romeo-forever

Use this endpoint to check if you have valid User credentials (username and password).

If you’re returned 200 OK, the credentials are valid.

Delete User

DELETE /api/account

Example

Deleting the juliet@buddycloud.com account using curl:

curl https://buddycloud.com/api/account \
     -X DELETE \
     -u juliet@buddycloud.com:romeo-forever

Removes a user account.

Change Password

POST /api/account/pw/change

Example

Changing the juliet@buddycloud.com’s password using curl:

curl https://buddycloud.com/api/account/pw/change \
     -X POST \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{ \
            "username": "juliet@buddycloud.com", \
            "password": "new-password" \
         }'

Changes the user’s password.

Reset Password

POST /api/account/pw/reset

Example

Resetting the juliet@buddycloud.com’s password using curl:

curl https://buddycloud.com/api/account/pw/reset \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{ "username": "juliet@buddycloud.com" }'

This resets the user’s password by sending a new password to the email address provided by the user during registration.

Channels

Channels are a group of publish-subscribe nodes. For example, the channel juliet@capulet.lit is an group of nodes owned by the user juliet@capulet.lit. Examples of such nodes that could be:

• /user/juliet@capulet.lit/posts node (the serialization of juliet@capulet.lit’s social activities)
• /user/juliet@capulet.lit/status node (a text string describing juliet@capulet.lit’s mood)
• /user/juliet@capulet.lit/music-i-liked node (a hypothetical activity stream of music juliet@capulet.lit likes)

Nodes

Nodes are publish-subscribe streams of posts with the same content type.

Each node has:

• publishers who can post new content;
• followers consumers of content;
• metadata (e.g. title, description and location fields).

Personal Nodes v. Topic Nodes

Buddycloud divides nodes into two categories: topic and personal.

For example, the channel juliet@capulet.lit comprises personal nodes for each type of information that juliet wants to share, such as her social activities, reflections on her mood, and the media she comments on.

Node Privacy Settings

Nodes may be private or public. Node Privacy is controlled by the node’s access_model:

The node metadata for public and private nodes is always publicly accessible.

Who creates the set of nodes for a channel?

Your application is responsible for creating the set of nodes it is going to use for a given channel. For example, the social application running at https://buddycloud.com automatically creates the following nodes everytime a new channel is created:

Create Node

POST /api/channelID/nodeID

Example

Creating a node called new-node using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/new-node \
    -X POST \
    -u juliet@buddycloud.com:romeo-forever

This allows creation of nodes.

Delete Node

DELETE /api/channelID/nodeID

Example

Deleting the node called new-node using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/new-node \
    -X DELETE \
    -u juliet@buddycloud.com:romeo-forever

This will remove a node.

Fetch Metadata

GET /api/channelID/metadata/nodeID

Example

Fetching the node new-node’s metadata using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/metadata/new-node \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever

Metadata allows you to describe the node, set defaults and even add a location to the node so that it will show up in nearby queries.

Node metadata is always visible for both public and private nodes.

Update Metadata

POST /api/channelID/metadata/nodeID

Example

Updating the node new-node’s metadata using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/metadata/new-node \
     -X POST \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Content-Type: application/json" \
     -d '{ \
            "title": "New Node Title", \
            "description": "Everything about Juliet", \
            "default_affiliation": "publisher" \
         }'

Use this endpoint to update a given node’s metadata.

Parameters

A complete set of node metadata is available from the Buddycloud protocol specification.

Posts

New posts to a node are automaticaly:

• pushed to the channel’s online followers
• spooled up for the channel’s offline followers
• archived and retrievable using the fetch posts method.
• indexed by the channel crawler

Different channel types have different post formats.

Field value examples:

Post Parameters

juliet@capulet.lit

O Romeo, Romeo! Wherefore art thou Romeo?

17163726-ea90-453e-ad25-455336a83fd4

[ { "id": "romeo-photo-id", "channel": "juliet@capulet.lit" } ]

9b7724d0-7ef5-4331-8974-81754abb7ba0

2012-11-02T03:41:55.484Z

2012-11-02T03:41:55.484Z

Pagination

Buddycloud uses Result Set Management for pagination of results obtained by the different endpoints for fetching posts specified below. This is useful when:

• building mobile applications and needing to limit the amount of data that the API sends back.
• your app needs to retrieve new messages since it was last online.

Query Parameters

You will pass pagination parameters via the URL query part.

Create Post

POST /api/channelID/content/nodeID

Example

Creating a new post to the posts node of romeo@buddycloud.com, using curl:

curl https://buddycloud.com/api/romeo@buddycloud.com/content/posts \
     -X POST \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Content-Type: application/json" \
     -d '{ "content": "O Romeo, Romeo, wherefore art thou Romeo?" }'

Response will be as follows:

HTTP/1.1 201 Created

Location: https://buddycloud.com/romeo@buddycloud.com/content/posts/$POST_ID

Use this endpoint to create new post to a given node.

Delete Post

DELETE /api/channelID/content/nodeID/postID

Example

Deleting post of id $POST_ID from the posts node of romeo@buddycloud.com, using curl:

curl https://buddycloud.com/api/romeo@buddycloud.com/content/posts/$POST_ID \
     -X DELETE \
     -u juliet@buddycloud.com:romeo-forever 

Removes a post from a node.

When a post is deleted,

• the post is deleted from the channel-node’s history,
• a retraction message is sent to online users.

Fetch Specific Post

GET /api/channelID/content/nodeID/postID

Example

Fetching specific post of id $POST_ID from the juliet@buddycloud.com/posts node, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/content/posts/$POST_ID \
    -X GET \
    -H "Accept: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "$POST_ID",
    "author": "romeo@buddycloud.com",
    "updated": "1595-06-01T12:00:00Z",
    "content": "But, soft! What light through yonder window breaks? It is the east, and Juliet is the sun.",
    "media": null
}

If you have interest in fetching a particular post whose $POST_ID is already known to you, you can use this endpoint for that matter.

For obvious reasons, this endpoint doesn’t support pagination. The other endpoints below potentially return multiple entries, with proper pagination support.

Fetch a Post’s Child Posts

GET /api/channelID/content/nodeID/postID/replyTo

Example

Fetching child posts of post to node juliet@buddycloud.com/posts of id $POST_ID using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/content/posts/$POST_ID/replyTo \
     -X GET \
     -H "Accept: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "$NEWEST_CHILD_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1595-06-01T12:00:00Z",
        "content": "But, soft! What light through yonder window breaks? It is the east, and Juliet is the sun.",
        "replyTo": "$POST_ID",
        "media": null
    },
    ...
    {
        "id": "$OLDEST_CHILD_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1591-06-04T12:00:00Z",
        "content": "Thus with a kiss I die.",
        "replyTo": "$POST_ID",
        "media": null
    }
]

Same endpoint using pagination

GET /api/channelID/content/nodeID/postID/replyTo? param=val&param=val…

Example

Fetching posts from a node using pagination, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/content/posts?after=$NEWEST_POST_ID \
     -X GET \
     -H "Accept: application/json"

Then, response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
    [Post with id == "NEWEST_CHILD_POST_ID" omitted]
    ...
    {
        "id": "$OLDEST_CHILD_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1591-06-04T12:00:00Z",
        "content": "Thus with a kiss I die.",
        "replyTo": "$POST_ID",
        "media": null
    }
]

Retrieves one or more posts that are children of a given node specified by $POST_ID using pagination ranges.

Fetch Recent Posts

GET /api/channelID/content/nodeID

Example

Fetching the most recent posts from the juliet@buddycloud.com/posts node, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/content/posts \
     -X GET \
     -H "Accept: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "$NEWEST_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1595-06-01T12:00:00Z",
        "content": "But, soft! What light through yonder window breaks? It is the east, and Juliet is the sun.",
        "media": null
    },
    ...
    {
        "id": "$OLDEST_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1591-06-04T12:00:00Z",
        "content": "Thus with a kiss I die.",
        "media": null
    }
]

Same endpoint using pagination

GET /api/channelID/content/nodeID? param=val&param=val…

Example

Fetching posts from a node using pagination, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/content/posts?max=3 \
     -X GET \
     -H "Accept: application/json"

Then, response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "$NEWEST_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1595-06-01T12:00:00Z",
        "content": "But, soft! What light through yonder window breaks? It is the east, and Juliet is the sun.",
        "media": null
    },
    ...
    {
        "id": "$OLDEST_POST_ID",
        "author": "romeo@buddycloud.com",
        "updated": "1591-06-04T12:00:00Z",
        "content": "Thus with a kiss I die.",
        "media": null
    }
]

Retrieves one or more posts using pagination ranges.

This is useful for retrieving recent posts to an individual node.

Often it’s useful to quickly show, for example, the 20 most recent posts. However some of these posts may reference a parent post outside of you apps' cache.

For another approach, please refer to the Fetch Recent Post Threads section depicted below.

Fetch Recent Post Threads

GET /api/channelID/content/nodeID/threads

Example

Fetching the most recent post threads from the juliet@buddycloud.com/posts node, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/content/posts/threads \
     -X GET \
     -H "Accept: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "$PARENT_POST_ID"
    "updated": "2015-01-30T01:39:00.070Z",
    "items": [
        {
            "id": "$OLDEST_CHILD_POST_ID",
            "author": "romeo@buddycloud.com",
            "updated": "1595-06-01T12:00:00Z",
            "content": "First reply.",
            "replyTo": "$PARENT_POST_ID"
            "media": null
        },
        ...
        [More Child Posts...]
        ...
        {
            "id": "$NEWEST_CHILD_POST_ID",
            "author": "romeo@buddycloud.com",
            "updated": "1595-06-01T12:00:00Z",
            "content": "Last thing ever said.",
            "replyTo": "$PARENT_POST_ID"
            "media": null
        },
        {
            "id": "$PARENT_POST_ID",
            "author": "romeo@buddycloud.com",
            "updated": "1591-06-04T12:00:00Z",
            "content": "First thing ever said.",
            "media": null
        }
    ]
  }
  ...
  [More Post Threads]
]

Retrieves one or more post threads, that is, collections of chained posts, using pagination ranges (where max depicts the maximum number of threads expected in the response).

Subscriptions

Retrieving a user’s channel subscription list will return the nodes that they follow and their affiliation with that node, which can be either:

• owner
• moderator
• publisher
• member
• outcast

…as well as the nodes where they have a subscription state of pending (which means the subscription is waiting to be approved).

Subscription Privacy

Users can only request their own subscriptions and are unable to view other user’s subscriptions.

Fetch Subscriptions

GET /api/subscribed

Example

Fetching subscriptions of juliet@buddycloud.com, using curl:

curl https://buddycloud.com/api/subscribed \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Accept: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "juliet@buddycloud.com/posts": "owner",
    "juliet@buddycloud.com/status": "owner",
    "romeo@buddycloud.com/posts": "pending",
    "capulet@topics.buddycloud.com/posts": "publisher"
}

Returns the user’s channel subscriptions as a JSON object.

The object’s keys are of the form {channel}/{node}.

The values denote the subscription type:

• owner
• moderator
• publisher
• member
• pending

Follow Channel

POST /api/subscribed

Example

juliet@buddycloud.com is subscribing to romeo@buddycloud.com/posts, using curl:

curl https://buddycloud.com/api/subscribed \
     -X POST \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Content-Type: application/json" \
     -d '{ "romeo@buddycloud.com/posts": "publisher" }'

Following behavior is dependent on the channel type:

• Following an open channel is automatically allowed.
• Following a private channel generates a pending subscription request

Following a private channel:

• the user is added to the channel’s pending subscription list
• the channel’s owner or a moderator receives a subscription request (immediately if they are online or queued up for when they come online)
• either the channels owner or any of the channels moderators approves (or rejects) and the result is then sent back to the user trying to follow the channel via a push notification
• the user’s subscription state is changed to subscribed, publisher (or none if rejected) depending on the channel’s default_affiliation

Unfollow Channel

Same endpoint as before, but passing ‘none’ in the payload

POST /api/subscribed

Example

juliet@buddycloud.com unfollows romeo@buddycloud.com/posts, using curl:

curl https://buddycloud.com/api/subscribed \
     -X POST \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Content-Type: application/json" \
     -d '{ \
             "romeo@buddycloud.com/posts": "none" \
         }'

Unfollowing a private channel removes the ability to read, upvote or delete posts.

Unfollowing a private channel will require re-requesting a subscription and re-approval of a moderator.

Followers

Followers of the nodes in a channel have one of the following affiliations:

The outcast affiliation is useful for dealing with abusive users.

Fetch Followers

GET /api/channelID/subscribers/nodeID

Example

Fetching followers of the romeo@buddycloud.com/posts node, using curl:

curl https://buddycloud.com/api/romeo@buddycloud.com/subscribers/posts \
     -X GET \
     -u romeo@buddycloud.com:juliet-forever \
     -H "Content-Type: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "romeo@buddycloud.com": "owner",
    "benvolio@buddycloud.com": "publisher"
}

This request returns a list of channel followers and their affiliation in the channel.

Retrieve Pending Followers

GET /api/channelID/subscribers/nodeID/approve

Example

Retrieving pending subscriptions to the romeo@buddycloud.com node, using curl:

curl https://buddycloud.com/api/romeo@buddycloud.com/subscribers/posts/approve \
     -X GET \
     -u romeo@buddycloud.com:juliet-forever \
     -H "Content-Type: application/json"

Response would be as follows:

HTTP/1.1 200 OK
Content-Type application/json

[
    {
        "subscription": "subscribed",
        "jid": "benvolio@buddycloud.com"
    },
    {
        "subscription": "pending",
        "jid": "juliet@buddycloud.com"
    },
    {
        "subscription": "pending",
        "jid": "tybalt@buddycloud.com"
    }
]

Retrieves the list of subscriptions of a node. Returns a list of objects containing the subscriber JID and the values of its subscription state (subscribed or pending).

Authorise Pending Followers

POST /api/channelID/subscribers/nodeID/approve

Example

Authorising subscription of juliet@buddycloud.com and denying to tybalt@buddycloud.com, using curl:

curl https://buddycloud.com/api/romeo@buddycloud.com/subscribers/posts/approve \
     -X POST \
     -u romeo@buddycloud.com:juliet-forever \
     -H "Content-Type: application/json" \
     -d '[ \
             { \
                 "subscription": "subscribed", \
                 "jid": "juliet@buddycloud.com" \
             }, \
             { \
                 "subscription": "none", \
                 "jid": "tybalt@buddycloud.com" \
             } \
         ]'

This allows a channel’s owner or moderator to approve or deny incoming subscription requests.

Alter Follower Affiliations

POST /api/channelID/subscribers/nodeID

Example

Changing juliet@buddycloud.com’s subscription affiliation to romeo@buddycloud.com/posts to member, using curl:

curl https://buddycloud.com/api/romeo@buddycloud.com/subscribers/posts \
     -X POST \
     -u romeo@buddycloud.com:juliet-forever \
     -H "Content-Type: application/json" \
     -d '{ \
             "juliet@buddycloud.com": "member" \
         }'

This enables users to promote (or e) user subscriptions to publisher, member or even moderator. By setting a subscription to outcast, the user is banned.

Media

File’s inherit the permissions of the channel they are shared with. For example sharing files onto a private channel will mean that only that channel’s followers can download them.

Media can be any type of file, and any file size (Buddycloud site administrators usually set about 1GB as a maximum size.)

Special MediaIDs

The media id of avatar is currently reserved and used for storing a channels avatar. Uploading with the avatar id will replace the user’s avatar.

List Media

GET /api/channelID/media

curl https://buddycloud.com/api/juliet@buddycloud.com/media \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "lETuJi8rPE4IfQrygN8rVtGx3",
        "fileName": "photo.jpg",
        "author": "juliet@buddycloud.com",
        "title": "Juliet's pic",
        "mimeType": "image/jpeg",
        "description": "Juliet's picture 1595/06/01",
        "fileExtension": "jpg",
        "shaChecksum": "bc46e5fac2f1cbb607c8b253a5af33181f161562",
        "fileSize": "60892",
        "height": "312",
        "width": "312",
        "entityId": "capulet@topics.buddycloud.com"
    }
]

This returns a list of all avaliable media objects in a channel.

Fetch Media

Get the raw media

GET /api/channelID/media/mediaID

Example

Retrieving the raw media of id $MEDIA_ID, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/media/$MEDIA_ID \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever

Get the media thumbnail preview

GET /api/channelID/media/mediaID?maxheight=val&maxwidth=val

Example

Retrieving a preview of the media of id $MEDIA_ID, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/media/$MEDIA_ID?maxheight=150&maxwidth=150 \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever

Get avatar

GET /api/channelID/media/avatar

Example

Retrieving avatar of juliet@buddycloud.com, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/media/avatar \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever

This request returns a media file.

The request can also be used to return an image preview or small user avatar sized files by adding the maxheight and maxwidth parameter to the request.

If the media object belongs to a public channel, you don’t need an Authorization header. Notice that if you’re building a web frontend, embedding public media from the media-server means just creating an <img> tag.

When both maxheight and maxwidth are requested the server will return a file smaller than or equal to both parameters.

Post Media

POST /api/channelID/media

Example

Posting new media to the capulet@topics.buddycloud.com channel, using curl:

curl https://buddycloud.com/api/capulet@topics.buddycloud.com/media \
     -X POST \
     -u juliet@buddycloud.com:romeo-forever \
     -H "Content-Type: application/json" \
     -d '{ \
             "data": "media data in bytes", \
             "content-type": "image/png", \
             "filename": "prom.png", \
             "title": "Juliet's prom pic", \
             "description": "Juliet's beautiful prom pic!" \
         }'

Response would be as follows:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "lETuJi8rPE4IfQrygN6rVtGx3",
    "fileName": "prom.png",
    "author": "juliet@buddycloud.com",
    "title": "Juliet's prom pic",
    "mimeType": "image/png",
    "description": "Juliet's beautiful prom pic!",
    "fileExtension": "png",
    "shaChecksum": "bc46e5fac2f1cbb607c8b253a5af33181f161562",
    "fileSize": 60892,
    "height": 312,
    "width": 312,
    "entityId": "capulet@topics.buddycloud.com"
}

This call enables media and media-metadata uploading and modification.

Posting new media will return the object id and metadata.

Updating existing media with the same id will overwrite the existing media content.

Delete Media

DELETE /api/channelID/media/mediaID

Example

Deleting media of id $MEDIA_ID from the juliet@buddycloud.com channel, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/media/$MEDIA_ID \
     -x DELETE \
     -u juliet@buddycloud.com:romeo-forever

Removes media from the channel.

Deleting media will remove it from the requested channel. This does not remove it from other channels where it has been reshared.

Fetch Media Metadata

GET /api/channelID/media/mediaID/metadata

Example

Fetching metadata of media of id $MEDIA_ID, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/media/$MEDIA_ID/metadata \
     -X GET \
     -u juliet@buddycloud.com:romeo-forever

Response would be as follows:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "lETuJi8rPE4IfQrygN8rVtGx3",
        "fileName": "photo.jpg",
        "author": "juliet@buddycloud.com",
        "title": "Juliet's pic",
        "mimeType": "image/jpeg",
        "description": "Juliet's picture 1595/06/01",
        "fileExtension": "jpg",
        "shaChecksum": "bc46e5fac2f1cbb607c8b253a5af33181f161562",
        "fileSize": "60892",
        "height": "312",
        "width": "312",
        "entityId": "capulet@topics.buddycloud.com"
    }
]

Endpoint used to fetch a given media’s metadata.

Update Media Metadata

PUT /api/channelID/media/mediaID

Example

Updating the media of id $MEDIA_ID’s name and title, using curl:

curl https://buddycloud.com/api/juliet@buddycloud.com/media/$MEDIA_ID \
     -X PUT \
     -u juliet@buddycloud.com:romeo-forever \
     -d '{ \
            "filename": "A good name for that picture of Jules", \
            "title": "A new title" \
        }' 

Use this endpoint to update a give media’s metadata.

The possible metadata parameters are:

Realtime

To get content updates in realtime directly through the REST API, your application can rely on long-polling an endpoint specifically designed with this goal in mind. The first section below depicts it in detail.

But to make your application truly aware of all kinds of Buddycloud events, you’ll need more.

If you’re building a mobile app, you can set it up so that it will listen for incoming push notifications when important events happen. The last sections below describe every step needed to make your app fully Buddycloud-powered.

Otherwise, the recommended thing is to have your app use XMPP-FTW. Please also refer to this guide with more on how to get started.

New Post Updates

First, get the last known timestamp

GET /api/notifications/posts

Example

Asking for the last known timestamp, using curl:

curl https://buddycloud.com/api/notifications/posts \
    -X GET

Response would be as follows:

{
    "last": "$LAST_TIMESTAMP",
    "items": []
}

Finally, start long polling

GET /api/notifications/posts?since=lastTT

Example

Using the last known timestamp to start long polling:

curl https://buddycloud.com/api/notifications/posts?since=$LAST_TIMESTAMP \
    -X GET

Once a new update arrives, response would be as follows:

{
    "last": "$LAST_TIMESTAMP_UPDATED",
    "items": [
        {
            "id": "$POST_ID",
            "source": "juliet@buddycloud.com/posts"
            "author": "romeo@buddycloud.com"
            "published": "2014-06-24T15:34:54.449Z",
            "updated": "2014-06-24T15:34:54.449Z",
            "content": "This the newest post in town",
            "media": null,
            "replyTo": "$PARENT_POST_ID"
        }
        ...
        [Potentially more posts from this node or other nodes here]
    ]

Don’t forget that the last known timestamp now is $LAST_TIMESTAMP_UPDATED!

Get New Post Updates By Long Polling

Use this endpoint to start long polling for new posts updates. Multiple updates shall arrive at a time, for all nodes the user is subscribed to (the user your app is currently working with).

Your application will need to provide the last known timestamp lastTT everytime it makes a new long polling request. On the right there are good examples of the intended flow of this process of getting new posts updates.

A new posts update should arrive in the form of a JSON response comprised of all the new posts' contents alongside information about the nodes that the new post belong to, respectively (the source key of each post has this value).

Push Notifications

Get SENDER ID From The Pusher

GET /api/notification_metadata?type=gcm

Example

Retrieving $SENDER_ID from the buddycloud.com’s Pusher service, using curl:

curl https://buddycloud.com/api/notification_metadata?type=gcm \
    -X GET \
    -u juliet@buddycloud.com:romeo-forever
    -H "Accept: application/json"

Response would be as follows:

{ "google_project_id": "$SENDER_ID" }

Do some work in your app to obtain a $REG_ID and then…

Send REGISTRATION ID To The Pusher

POST /api/notification_settings

Example

Sending $REG_ID when registering with buddycloud.com’s Pusher service, using curl:

curl https://buddycloud.com/api/notification_settings \
    -X POST \
    -u juliet@buddycloud.com:romeo-forever \
    -H "Content-Type: application/json" \
    -d '{ \
           "type": "gcm", \
           "target": "$SENDER_ID" \
    }'

Alongside the type and target keys, you can specify specific events you want to monitor (or not). By default you’ll monitor most events. More information about this can be found here.

Get Push Notifications By Registering With The Pusher Service

There’s some work you will have to do in your mobile application in order to enable it to receive Buddycloud updates via push notifications, sent by our Pusher service. It will need to become a Google Cloud Messaging client so that it’s able to receive those updates. Please refer to this guide and perform instructions given there.

Then, you will use some API calls in order to talk to our Pusher server so that you can register your application with it. In short, you’ll need to get a SENDER_ID from the Pusher, use it within your application to register with Google Cloud Messaging and then send your REG_ID back to the Pusher to register with it too. This guide explains the process more thoroughly and on the right you can find the specs of both endpoints used alongside short examples.