Socialwg/Social API/pump.io API
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.
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.
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.
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.
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.
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")
- *favorite *
- *like* (synonym for "favorite")
- *unfavorite *
- *unlike *(synonym for "unfavorite")
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.
- 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.
- 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.
- 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.
- 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.)
- 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.)
- get /api/user/nickname/lists/type
- Users can make lists; this returns a collection of those lists. They will typically be "collection" objects.
- 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.
- get /api/activity/uuid
- put /api/activity/uuid
- del /api/activity/uuid
- Read, update and delete an activity.
- 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.
- 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.
- 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.
HTTP verb stats
For identi.ca, a big pump.io installation, these are rough stats for different HTTP verbs.
- Understanding pump.io -- an overview of the pump.io API