Socialwg/Social API/pump.io API

The pump.io API is implemented by pump.io and GNU MediaGoblin. There are a number of clients for the Web, desktop, and mobile devices.

This review covers the client-to-server aspects of the API and ignores the federation aspects; for example, it doesn't cover Dialback authentication, proxying remote content, or posting to a user's inbox.

Overview

The API uses Activity Streams 1.0 as its on-the-wire format. There is no support for the Activity Streams Atom or any XML format.

Internally it models a one-directional follow network, groups, and contact lists.

It uses the Activity Base Schema for typical social object types (person, group, image, note) and social verbs (create, follow, join).

The API uses OAuth 1.0 for authentication.

The API below has 42 endpoints.

Audience

The API used Audience Targeting for JSON Activity Streams for routing of activities. If a user posts an activity without any audience specified, the server will provide common-sense audience elements (e.g., if something is in-reply-to another thing, add the author of the other thing as part of the audience).

Audience can be a user; a group; a contact list; the user's followers (default); or "the public". Activities posted to the public are distributed to followers but readable by anyone.

Feeds

Each user has two main feeds: an outbox of activities they have created (posting notes, following other users, joining groups, etc) and an inbox of activities that they have received. A user receives an activity if they were in the audience for the activity.

Each feed also has "sub-feeds" that divide into major and minor activities. "Major" activities are primarily creation of new content or sharing content; minor activities are commenting on other content, changing the social graph, participating in games, etc.

The inbox also has a "direct" sub-feed, which contains only those activities for which the user was directly addressed. This is useful for seeing only the user's "direct messages". It in turn has major and minor subfeeds.

Discovery

Users are identified by Webfinger acct: URIs. Locations of their feeds and social graph endpoints can be discovered using Webfinger.

The API uses Responses for Activity Streams to specify collections related to an activity object -- likes, followers, etc. The "links" collection is also used.

Entities

The API can handle activities of any type, including extension types. It will route them via the addressing properties.

pump.io (and other implementations, probably) use these verb types to modify internal behaviour.

*post *
*create* (synonym for "post")
*follow*
*stop-following*
*favorite *
*like* (synonym for "favorite")
*unfavorite *
*unlike *(synonym for "unfavorite")
*delete*
*update*
*add*
*remove*
*share*
*unshare*
*join*
*leave*

Of these, three are for CRUD on content ("post", "delete", and "update"), six are for social graph management ("follow" and "stop-following", "join" a group and "leave", "add" to and "remove" from a contact list), and four are for responses ("favorite" and "unfavorite", "share" and "unshare" -- posting a comment in-reply-to something is handled differently).

These are the object types supported internally by pump.io.

*application*
*audio*
*binary*
*collection*
*comment*
*file*
*group*
*image*
*note*
*person*
*place*
*video*

source

Endpoints

Users

get /api/users: Site-wide collection of users.

post /api/users: Create a new user.

get /api/user/nickname
put /api/user/nickname
del /api/user/nickname: Read, update and delete a user.

get /api/user/nickname/profile
put /api/user/nickname/profile: Read and update a user profile. Note that profile is separate from the user object.

get /api/whoami: Redirect to the current authenticated user.

User feed

get /api/user/nickname/feed: Collection of activities created by the user.

post /api/user/nickname/feed: Create a new activity. May have side-effects if the verb is recognized.

get /api/user/nickname/feed/major
get /api/user/nickname/feed/minor: Read major and minor activities by a user.

post /api/user/nickname/feed/major
post /api/user/nickname/feed/minor: Create new major and minor activities.

Inbox

get /api/user/nickname/inbox: Get activities that were addressed to the user, directly or indirectly.

get /api/user/nickname/inbox/major
get /api/user/nickname/inbox/minor
get /api/user/nickname/inbox/direct
get /api/user/nickname/inbox/direct/major
get /api/user/nickname/inbox/direct/minor: Major, minor, direct, and variations on that theme, for the inbox.

Social graph

get /api/user/nickname/followers: Get a user's followers; collection of activity objects.

get /api/user/nickname/following: Get who a user is following; collection of activity objects, typically "person".
post /api/user/nickname/following: Follow a new user. (Can also just post a "follow" activity to user's feed.)

Likes

get /api/user/nickname/favorites: Get a collection of objects the user has "liked" or "favorited".
post /api/user/nickname/favorites: Like an object. (Can also just post a "follow" activity to user's feed.)

Lists

get /api/user/nickname/lists/type: Users can make lists; this returns a collection of those lists. They will typically be "collection" objects.

Media upload

get /api/user/nickname/uploads: Get media objects the user has uploaded.
post /api/user/nickname/uploads: Upload a new object. This is kind of a complicated process.

Activities

get /api/activity/uuid
put /api/activity/uuid
del /api/activity/uuid: Read, update and delete an activity.

Collections

get /api/collection/uuid/members: Get members of a collection.
post /api/collection/uuid/members: Add a new member to a collection. "add" and "remove" activities also work.

Groups

get /api/group/uuid/members: Which members have joined the group.
get /api/group/uuid/inbox: Activities addressed to the group.
get /api/group/uuid/documents: Documents owned by the group.

Objects

get /api/type/uuid: Get a JSON representation of an object. The type is the Activity Object objectType. Unrecognized types have type "other".

put /api/type/uuid: Update an object. This is similar to posting an "edit" activity.

del /api/type/uuid: Delete an object. This is similar to posting a "delete" activity.

get /api/type/uuid/likes: Collection of people who have "liked" the object.

get /api/type/uuid/replies: Collection of comments or other object types that have been posted "in reply to" this object.

get /api/type/uuid/shares: Collection of people who have shared this object.

Other notes

HTTP verb stats

For identi.ca, a big pump.io installation, these are rough stats for different HTTP verbs.

Verb	Count
GET	22359258
POST	445473
PUT	3803
DELETE	40