Manybots Server API doc

Overview

Manybots' API allows developers to post and read activities from users' accounts.

The API uses OAuth for authentication and deals with activities in the Activity Streams 1.0 JSON format. In fact it only consumes and returns data in the JSON format.

The applications you develop can be used to post activities into a user's stream, to read a user's stream, or to do both. For example, you could develop an application that tracks a user's activity in a specific Task Management application and posts them to Manybots, or create an application that fetches all the tasks on users' stream, coming from any application, and gives an overview of all tasks on all projects, on all apps.

Using Activity Streams

You opened this page in your browser. If you wanted to share that activity with the world, how would you describe it programatically?

Activity Streams provides an answer. To make it simple:

  • You: the actor
  • open: the verb
  • this page: the object
  • your browser: the target

Or when you publish a post on your blog:

  • You: the actor
  • post: the verb
  • article: the object
  • blog: the target

The actor, verb, object and target have standardized values and properties. Manybots uses this format to allow users and developers to create and read all kinds of different activities in a unified way.

This way, all developers have to do is make normal POST and GET requests of JSON objects that describe any activity.

You can learn the specifics in the Activities section of this documentation.

Guides, examples and libraries

Well, there isn't much yet. But there's enough to get started -- maybe you'll be able to share your experience, we'll be happy to link to your page.

API Methods

OAuth Authentication

Before you start talking to the Manybots API, you need to register your application in order to obtain your app's OAuth tokens.

You can start by registering your application. You'll need to be logged in.

For the application developer, Manybots's OAuth flow works just like Twitter's, so you should be able to find a bunch of tutorials and code out there to help you get started with OAuth in your favorite language.

Since Manybots allows "streaming" authentication from other Identity Providers though, Manybots users that are not already logged in when your app requests them to authenticate are likely to experience a streamed authentication flow within the Manybots authentication flow. Identities flowing. Pretty cool, huh?

User profile

When the user is authenticated, the first thing you'll probably want to do is grab their profile information from the Manybots Server in order to setup an account for them in your application.

All you have to do is make a GET request to the "/me.json" endpoint. A JSON object containing the user profile information will be returned and you'll use that data to identify the user, personalize their experience with your application, and probably to provide user information when creating Activities.

You should treat the user's ID as provided by Manybots as the user's identifier on your app (at least with regards to Manybots), since all other attributes can change.

Endpoint

Make an authenticated GET request to

/me.json

Content-type: application/json

Request format

No parameters are needed

Response format

Activities

Activities are the heart of Manybots. They are meant to be Activity Streams 1.0 compliant.

As a result, any kind of human or machine generated activity can be represented solidly in Manybots and linked back directly to the original objects of the activity, as long as they're accessible from the Web. Up to you to find the best ways to capture activities from your and other people's life.

With simple POST and GET requests and some JSON parsing you'll be generating and analyzing activities in no time.

Creating activities

To create an activity in Manybots Server, you first build an activity object in your app and then post it to Manybots on behalf of a User.

The activity object you send to Manybots will be passed back to if it was correctly saved, and the very same object will be passed to all apps that consume the activities feed of your users.

Manybots doesn't provide an ID other than the ones you provide - you are responsible for the information you pass on to Manybots.

The only exception to this behavior is the use of the very helpful Auto Title feature, also explained in this document.

Endpoint

Make an authenticated POST request to

/activities.json

Content-type: application/json

Request format
Response format

Returns the same object.

Reading all activities

Endpoint

Make an authenticated GET request to /activities.json

Request format
No parameters allowed at this point.
Response format

Auto Title feature

One of the fundamental jobs of Activity Streams is to provide easy ways to generate the sentence that is displayed to viewers from a formatted object. In case the service dealing with an activity can't figure out how to parse it, they may use the "title" attribute as the sentence to display.

In order to avoid over-engineering a parser and to try and simplify things for developers, Manybots Server provides a feature called Auto Title that combines both options.

What it does

Auto Title allows developers to write their "title" fields like this

ACTOR added an OBJECT to TARGET

Manybots Server will automatically replace these upcase strings with the information contained in the activity object.

If the activity has no target, you can ommit the keyword TARGET. ACTOR and OBJECT are mandatory.

So, when posting activities, you can use the Auto Title to easily write up the sentence that will be displayed to the viewer.

The activity will be saved with the replaced values. The keyword structure is not saved nor passed on to other apps.

How to use it

First, when posting the activity's title attribute must have a value that complies with the structure explained above.

Then you only need add the following attribute to the activity object:

{ ..., "auto_title": true, ... }

Error Handling

Errors can be:

  • 401 Unauthorized: The OAuth tokens may have been revoked by the user or you're not authenticating properly
  • 422 Unprocessable entity: Your request is malformed. Field errors are returned within the response object.
  • 406 Not acceptable: The Content-type or URL you're using to make the request isn't valid.
  • 500 Internal server error: The Manybots Server has an error. If this should happen, please notify support.