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.
Contents
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*
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 |
See also
- Understanding pump.io -- an overview of the pump.io API
