The Social API

Status of this document

2015-10-20 Document moved to W3C-Social Editor’s Draft. This document will no longer be updated.

An overview of the current state of specs that are inputs to the WG: ActivityPump, the Indieweb ecosystem (including Micropub and Webmention) and SoLiD; all of which are subject to ongoing development. Arranged based on Social API Requirements.

Optimistically, this has the potential to become a unified working draft. Ultimately an implementation of any subsection of this spec should be compatible with the equivalent subsection of one of the aforementioned specs. Sometimes the overlap between spec subsections is unclear (to me), which is where I’ve written all options out for now.


People and the content they create are the core componants of the social web; they make up the social graph. This document describes a standard way in which people can:

regardless of what that content is or where it is stored.

This provides the core building blocks for interoperable social systems.

This specification is divided into parts that can be implemented independantly as needed, or all together in one system, as well as extended to meet domain-specific requirements. Users can store their social data across any number of compliant servers, and use compliant clients hosted elsewhere to interact with their own content and the content of others. Put simply, this specification tells you:


Each stream MUST have a globally unique identifier (HTTP URI). Each object in a stream MUST have a globally unique identifier (HTTP URI) in the @id property, and MAY contain only this identifier, which can be dereferenced to retrieve all properties of an object.

A GET on the identifier retrieves JSON[-LD] representation of the object or stream of objects, or an HTML representation from which the equivalent JSON representation can be parsed.

Content representation

Content SHOULD be represented according to ActivityStreams (JSON or JSON-LD) but MAY be structured according to an alternative syntax (eg. HTML with Microformats2 or HTML with RDFa).

Content SHOULD be described using the ActivityStreams vocabulary, but MAY use other vocabularies instead.

TODO: limit/paging

Microformats uses url not @id

TODO: Example single object.

TODO: Example stream of objects.

Creating content

POST a JSON object (see content representation) to the appropriate endpoint.

Some people want things to be RESTish..


Updating an object SHOULD have the side effect of notifying those subscribed and mentioned.


Deleting an object SHOULD have the side effect of notifying those subscribed and mentioned.

When an object is deleted, it SHOULD be replaced with a ‘tombstone’ containing its unique identifier, deleted (or last updated) date, and optionally replacement content (eg. “this post was removed”). Its URI SHOULD return a 410.

Note: using SHOULD not MUST to allow for silently deleting objects


One user may publish one or more streams of content. Streams may be generated automatically or manually, and might be segregated by post type, topic, audience, or any arbitrary criteria decided by the curator of the stream. The result of a GET on the HTTP URI of a profile MAY include links to other streams, which a consumer could follow to read or subscribe to. Eg.

<link rel="feed" href="">

HTTP/1.1 200 OK .... Link: <>; rel="feed"

How to include additional info, eg. title/description of feed?


An agent (client or server) may ask to be notified of changes to a content object (eg. edits, new replies) or stream of content (eg. objects added or removed from the stream).

Lots of ways of doing this, what to use?

Here are some options…

A server may also receive notifications of changes to content it has not subscribed to: see mentioning.


(was ‘Notifications’)

A user may wish to push a notification to another user, for example because they have linked to (replied, liked, bookmarked, reposted, …) their content or linked to (tagged, addressed) the user directly.

Note: we need to leave it open for users to refuse content they have not explicitly subscribed to, ie. nothing else should rely on implementation of Mentioning.


The subject of a profile document can be a person, persona, organisation, bot, location, …whatever. Each profile document MUST have a globally unique identifier (HTTP URI). Performing a GET on a profile document SHOULD return a JSON object containing attributes of the subject of the profile; MAY return objects the subject has created, such as an ActivityStreams Collection; and SHOULD return at least one link to a stream of content (see discovery). The JSON representation of a profile document MAY be parsed from an HTML representation (eg. via Microformats (h-card) or RDFa).



Note: a user should not be required to publish their friends/followers, or may selectively publish them. However, if they’re going to (which is useful for eg. switching readers without having to resubscribe to everyone) we should make sure there’s a standard way of doing it.

Note: I think defining a vocabulary for types of relationships is out of scope and generally not very useful.

Authorization and access control

TODO: Access control