Socialwg/Social API/ API

From W3C Wiki
Jump to: navigation, search

The API is implemented by 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.


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. (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

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




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.


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.)


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.

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.


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.

Other notes

HTTP verb stats

For, a big installation, these are rough stats for different HTTP verbs.

Verb Count
GET 22359258
POST 445473
PUT 3803

See also