davidbgk
/
larlet-fr-david-cache

title: A highly opinionated guide to learning about ActivityPub
url: https://tinysubversions.com/notes/reading-activitypub/
hash_url: 8440372c6df33b8f23cfce7a9eca5961

<p><em>by Darius Kazemi, Jun 1, 2019</em></p>
<p>This document is for programmers who take one look at <a href="https://activitypub.rocks">activitypub.rocks</a>, click on through to the documentation, and can't make heads or tails of it.</p>
<p>In other words this document is for me, one year ago.</p>
<p><strong>IMPORTANT NOTE: This document does not explain ActivityPub. It explains <em>how to learn about ActivityPub</em>.</strong></p>
<p>If you want THE ULTIMATE TL;DR, just <a href="#the-ultimate-tl-dr">skip to that section</a>.</p>
<h2 id="introduction">Introduction</h2>
<p>The one big misunderstanding that a programmer can have when attempting to learn about ActivityPub is to assume that all the information you need is in the ActivityPub spec! Really, to learn about ActivityPub in such a way that it will be useful in a concrete sense, you need to be familiar with three specs:</p>

<p>Those two extra documents are in fact mentioned in the ActivityPub spec itself, so I'm not claiming that they are somehow hidden. But I'm a lazy, impatient reader. When I'm given a spec like ActivityPub that is ~10,000 words of spec language... well. I'm going to try and take all the shortcuts I can.</p>
<p>I thought I was the only programmer with this problem, but as I spoke to more and more people at conferences, I realized there are many others who, for example, look at ActivityPub and yet have no idea there exists an Activity Vocabulary spec.</p>
<h3 id="start-with-activity-vocabulary">Start with Activity Vocabulary</h3>
<p>I am a concrete thinker. I don't like reading about a system for passing messages between computers if I can't have some sort of understanding of <em>what exactly</em> is being passed around.</p>
<p>Unfortunately, the ActivityPub spec is mostly all about the "publication" part and not the "what data are we sending around" part.</p>
<p>For this reason, <strong>I recommend that you start your journey into ActivityPub by first reading the <a href="https://www.w3.org/TR/activitystreams-vocabulary/">Activity Vocabulary spec</a></strong>.</p>
<h2 id="reading-activity-vocabulary">Reading Activity Vocabulary</h2>
<p>This spec is in five non-appendix sections:</p>
<ol>
<li>Introduction</li>
<li>Core Types</li>
<li>Extended Types</li>
<li>Properties</li>
<li>Implementation Notes</li>
</ol>
<h3 id="introduction">Introduction</h3>
<p>The intro is brief, and is your usual spec boilerplate about  the definitions of MUST and SHOULD.</p>
<h3 id="core-types">Core Types</h3>
<p>"Core Types" is where you might think you should start. It's the core, right? Well, you're wrong. The first thing you're hit with is a definition of <strong>Object</strong>:</p>
<blockquote>
<p>Describes an object of any kind. The Object type serves as the base type for most of the other kinds of objects defined in the Activity Vocabulary, including other Core types such as Activity, IntransitiveActivity, Collection and OrderedCollection. </p>
</blockquote>
<p>The example given is:</p>
<pre><code>{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Object",
  "id": "http://www.test.example/object/1",
  "name": "A Simple, non-specific object"
}
</code></pre><p>Wow. That's real useful. Now I know how to define a non-specific thing with no properties.</p>
<p>(Aside: this "begin from first principles" thing is a problem with almost all spec writing. It is largely <em>how specs are written</em> and it fucking blows. The authors of these documents are just following tradition and I do not wish to paint these specs as particularly bad.)</p>
<p>Just skip the Core Types for now and move onto section 3, Extended Types.</p>
<h3 id="extended-types">Extended Types</h3>
<p>Ah, Extended Types. Or as I like to call them: the actually-useful types. Something like 50% of the stuff you actually care about is in this section.</p>
<p>We are given three major kinds of "types". (Um, by the way, this isn't quite a "type" as you may know it. It's really more like a JSON data format.)</p>
<ul>
<li>Activity Types</li>
<li>Actor Types</li>
<li>Object Types</li>
</ul>
<h4 id="activity-types">Activity Types</h4>
<p>We are once again immediately hit over the head with this doozy of a sentence:</p>
<blockquote>
<p>All Activity Types inherit the properties of the base <strong>Activity</strong> type.</p>
</blockquote>
<p>While this does make sense in a highly specific way that is unique to specification writing, please just skip this sentence and all sentences like it (there is at least one other saying the same thing about Object Types).</p>
<p>Best to avoid the near-tautological definitions required for writing things like parsers and instead skip to the concrete stuff. Scroll down and you'll see that Activity Types include things like:</p>

<p>Hey!! This is good! This is like... stuff that users do on social networks. Now we're getting somewhere.</p>
<p>Browse over all the activities. Look at the "Notes" section and glance at the example JSON object. There are some interesting activity types in there! For example, there's <strong>Question</strong>, which is the activity type that Mastodon uses in its implementation of polls. And there's <strong>Travel</strong>, which is meant to indicate movement from geographic (or even conceptual) point A to point B! You might make extensive use of this if your social network supported a Facebook style "I've checked in to New York City right now" post. There's even a <strong>View</strong> activity, which can be used for read receipts.</p>
<p>Anyway, read 'em.</p>
<h4 id="actor-types">Actor Types</h4>
<p>An <strong>Actor</strong> is what you might think of as a user agent. It can be a person, a bot, a company, a group of people, and more. But the important thing is: an <strong>Actor</strong> is the <em>thing that is doing</em> an <strong>Activity</strong>.</p>
<p>So a normal post to Mastodon is a <strong>Person</strong> actor doing a <strong>Create</strong> activity (what is being created is defined in the next section, Object types). Or if a company sent out discount codes to its followers, that would be an <strong>Organization</strong> doing an <strong>Offer</strong> activity.</p>
<p>There aren't many <strong>Actor</strong> types listed so just read them all.</p>
<h4 id="object-types">Object Types</h4>
<p>Yeah. I know. "Object" is probably the most overloaded English word in programming and we're already on our second thing called an object in this one spec. I'm sorry. Deep breaths, we'll get through this.</p>
<p>Anyhow. These are the meat and potatoes of what actually gets sent around these networks. Object types include:</p>

<p>...and several more. So when you make a regular text post to Mastodon, that is a case where a <strong>Person</strong> will <strong>Create</strong> a <strong>Note</strong>.</p>
<h4 id="putting-it-all-together">Putting it all together</h4>
<p>Here's some code from <a href="https://github.com/dariusk/express-activitypub/">a small ActivityPub reference implementation I wrote</a></p>
<pre><code>  let noteMessage = {
    'id': `https://${domain}/m/${guidNote}`,
    'type': 'Note',
    'published': d.toISOString(),
    'attributedTo': `https://${domain}/u/${name}`,
    'content': text,
    'to': ['https://www.w3.org/ns/activitystreams#Public'],
  };

  let createMessage = {
    '@context': 'https://www.w3.org/ns/activitystreams',

    'id': `https://${domain}/m/${guidCreate}`,
    'type': 'Create',
    'actor': `https://${domain}/u/${name}`,
    'to': ['https://www.w3.org/ns/activitystreams#Public'],
    'cc': [follower],

    'object': noteMessage
  };
</code></pre><p>I construct the <strong>Note</strong> object and the <strong>Create</strong> activity. The <strong>Note</strong> object gets embedded inside the <strong>Create</strong> activity, which indicates that we are <strong>Creat</strong>-ing a <strong>Note</strong>. What about the <strong>Person</strong>? That's implied in the 'actor' field of the <strong>Create</strong>, and that URL is the equivalent of passing the <strong>Person</strong> by reference. Any program parsing this out could query that URL and get the JSON of the <strong>Person</strong> from there.</p>
<h3 id="properties">Properties</h3>
<p>If you're wondering what those "id", "cc", and so on fields mean, you're in luck. Those are described in this section, which contains the <em>other</em> 50% of the stuff you care about.</p>
<p>Read this section, if only to familiarize yourself with what's here. That way you'll know to come back here when you see something like "prev" in a JSON object and wonder how that's supposed to be constructed.</p>
<h3 id="implementation-notes">Implementation Notes</h3>
<p>This is where the concrete examples of things like "how to represent a friend request" live. Definitely worth reading this section as well, though on a first run through you really only need to read:</p>
<ul>
<li>5.1: Audience targeting (not about advertising, this is about what the "to" and "cc" fields mean. It's the difference between a direct message and a public message, for example.)</li>
<li>5.2.1: Modeling a "friend request"</li>
<li>5.5: How <strong>Undo</strong> does and does not work</li>
<li>5.8: A nice conceptual grouping of what circumstances you might use different Activities in</li>
</ul>
<h2 id="reading-activitypub">Reading ActivityPub</h2>
<p>Next, read <a href="https://www.w3.org/TR/activitypub/">the ActivityPub spec</a>. It's in seven major sections:</p>
<ol>
<li>Overview</li>
<li>Conformance</li>
<li>Objects</li>
<li>Actors</li>
<li>Collections</li>
<li>Client to Server Interactions</li>
<li>Server to Server Interactions</li>
</ol>
<p>But first, a word about JSON-LD.</p>
<h3 id="a-note-on-json-ld">A note on JSON-LD</h3>
<p>Starting with the ActivityPub spec, you're going to see <a href="https://json-ld.org/">JSON-LD</a> mentioned a bunch. You don't have to care about this at all. For our purposes it's JSON with some specific property names in it, and where you follow links to complete the content of an object. Is this technically 100% correct? No. But if you were the kind of person who cared about the difference between JSON-LD and JSON, you'd probably be writing your own spec right now instead of reading this article.</p>
<h4 id="following-links-in-json">Following links in JSON</h4>
<p>One important thing to note about the kind of JSON stuff you'll be seeing is that you'll often see a URI embedded in a JSON object. Take the following example of an object with no URI anywhere in it:</p>
<pre><code>{
  "id": 1234,
  "object": {
    "type": "Note",
    "content": "Hello world."
  }
}
</code></pre><p>Other times you'll see something like:</p>
<pre><code>{
  "id": 1234,
  "object": "https://example.com/5678"
}
</code></pre><p>But then if you do a GET request with the appropriate headers to "<a href="https://example.com/5678">https://example.com/5678</a>", you'll get</p>
<pre><code>{
  "type": "Note",
  "content": "Hello world."
}
</code></pre><p>These two JSON things comprise the exact same information as that first JSON thing. It's just split across two HTTP requests. When you encounter a URI in one of these JSON objects, the idea is to follow the URI in order to resolve it into plain JSON and consider that the sub-object.</p>
<h3 id="overview">Overview</h3>
<p>Read this whole thing. You probably tried to read this once, before reading the Vocabulary spec, and if you're anything like me you were extremely confused. I promise it will be less confusing this time.</p>
<p>Basically it explains that you're taking these JSON things described in the Vocabulary spec and POSTing them to specific API endpoints, which process them.</p>
<h3 id="conformance">Conformance</h3>
<p>A short section that you might as well read. This is where it's made clear that this document actually describes <em>two separate protocols</em>. There is a Client to Server (C2S) and Server to Server (S2S).</p>
<p>In order to make your service "federated" via ActivityPub, <em>the only protocol you really care about is the server to server protocol</em>. S2S is how a Mastodon server can talk to a Pleroma server can talk to a Pixelfed server etc etc. Federation as we know it.</p>
<p>The C2S protocol is about <em>user choice</em>. It's a good thing, but it has nothing to do with federation. It's a standard way for user client software, like a phone app, to talk to a server. If we lived in a world where Mastodon and Pleroma and Pixelfed all used the C2S protocol, then in theory I could easily write a phone app that connects to all three of those services, and users could mix and match clients with servers to their heart's delight. A new service could pop up that I didn't even know about, but if it used C2S my phone app would be minimally compatible with it. (We do not live in this world, most federated services do not implement C2S, but this is the vision, to my understanding.)</p>
<h3 id="objects">Objects</h3>
<p>This will be a much easier read now that you've read over the Vocabulary document.</p>
<p>Specifically, sections 3, 3.1, and 3.2 are really important and discuss why, for example, if you send a message to a remote server, it should have some way of querying your server to confirm the message. I originally thought that I could get away with just sending messages into the void and not storing them in a local database, but I was wrong, because remote servers need to confirm that it's not just some random person claiming to send content from my own origin.</p>
<h3 id="actors">Actors</h3>
<p>So an ActivityPub actor is an Activity Vocabulary actor, with the mandatory addition of an inbox and and outbox, which are typically URIs that you either GET or POST to depending on what you want to do with them. For example, you can GET from a user's outbox URI and receive a JSON list of posts. Try it on my outbox from Friend Camp right now in your web browser by <a href="https://friend.camp/users/darius/outbox">browsing to this URL</a>. You should see something like this:</p>
<pre><code>{
  "@context":"https://www.w3.org/ns/activitystreams",
  "id":"https://friend.camp/users/darius/outbox",
  "type":"OrderedCollection",
  "totalItems":5688,
  "first":"https://friend.camp/users/darius/outbox?page=true",
  "last":"https://friend.camp/users/darius/outbox?min_id=0&amp;page=true"
}
</code></pre><p>If you click through to <a href="https://friend.camp/users/darius/outbox?min_id=0&amp;page=true">the "last" URI</a>, you'll get 20 of my oldest posts from Friend Camp, including <a href="https://friend.camp/@darius/100538943364185987">this charmer</a>.</p>
<p>Anyway, read this whole section too. It's short.</p>
<h3 id="collections">Collections</h3>
<p>Skip this for now. You'll absolutely want to come back to this later but you can probably figure out what collections are in context of their usage (hint: that outbox JSON is a type of collection; it contains paging data for iterating through collections of stuff).</p>
<p>But seriously just skip this for now, you don't need to muddy your brain with it.</p>
<h3 id="client-to-server-interactions">Client to Server Interactions</h3>
<p>Look. If you want to support a universal client ecosystem, go ahead and read this section. But if you just want to write a federated service, skip it and come back to it later.</p>
<h3 id="server-to-server-interactions">Server to Server Interactions</h3>
<p>Read this whole thing. This one section, combined with the Activity Vocabulary spec, forms the absolute basics of getting a federated service up and running. The Vocabulary spec tells you <em>what</em> to send, and this section tells you <em>how</em> to send it.</p>
<p>Among other things, it discusses the difference between an <code>inbox</code> and a <code>sharedInbox</code>. It talks about how to <strong>Follow</strong> an <strong>Actor</strong>, and how someone might <strong>Accept</strong> or <strong>Reject</strong> a follow request. It talks about <strong>Announce</strong>, which in addition to literally being for announcements, is also your standard "sharing" activity, like an RT on Twitter or a boost on Mastodon.</p>
<h2 id="reading-activitystreams-2-0">Reading ActivityStreams 2.0</h2>
<p>Eh. Don't read it now. Skim the table of contents. There will be bits of ActivityPub that don't make sense without the ActivityStreams 2.0 spec, but those will be more advanced questions you'll have later.</p>
<h2 id="the-ultimate-tl-dr">THE ULTIMATE TL;DR</h2>
<ul>
<li>Read the <a href="https://www.w3.org/TR/activitystreams-vocabulary/">Activity Vocabulary spec</a>, sections 3, 4, 5.1, 5.2.1, 5.5, and 5.8</li>
<li>Read the <a href="https://www.w3.org/TR/activitypub/">ActivityPub spec</a>, sections 1, 2, 3, 4, and 7</li>
<li>Familiarize yourself with the table of contents for the <a href="https://www.w3.org/TR/activitystreams-core/">ActivityStreams 2.0 spec</a>.</li>
</ul>
<h2 id="go-forth-and-make-stuff">Go forth and make stuff</h2>
<p>Assuming you&#39;ve done all this reading, the knowledge you have right now should hopefully be enough to start hacking on sending simple messages via ActivityPub.</p>
<p>I recommend reading these two articles by Eugen Rochko, the creator of Mastodon:</p>
<ul>
<li><a href="https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/">How to implement a basic ActivityPub server</a></li>
<li><a href="https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/">How to make friends and verify requests</a></li>
</ul>
<p>If you&#39;re like me and you enjoy poking around at a simple implementation, I have written a bare bones JavaScript ActivityPub server using the popular Express application framework:</p>
<ul>
<li><a href="https://github.com/dariusk/express-activitypub">Express ActivityPub Server</a></li>
</ul>