A Developer’s Guide to ActivityPub and the Fediverse
If you keep an eye on developments in social media, you can’t have failed to notice the recent extraordinary rise of ActivityPub, a W3C protocol enabling decentralized social networking between federated servers.
What was once a somewhat niche protocol and open standard for building interoperable social apps has gained real traction in the wake of Elon Musk’s purchase, and subsequent transformation, of Twitter.
Mastodon is still the most significant implementation of ActivityPub, but as the benefits of social networks that aren’t centrally controlled by one company become an increasingly salient issue, more platforms have begun to integrate themselves into the ‘fediverse’.
The first step for planning an ActivityPub integration is to figure out how different aspects of your software map to the Activity Streams format.
– Evan Prodromou, ActivityPub spec co-author.
These include WordPress.com; Ghost; Flipboard, and Meta’s Elon-challenger, Threads.
If you want to understand the thinking behind ActivityPub, The New Stack recently explored the fundamentals in depth, in a podcast interview with co-author of the protocol, Evan Prodromou.
But how do you get started if you want to integrate your own software with ActivityPub? Prodromou has written a new book on this very topic, and we caught up with him to explore the practicalities of linking up with the fediverse.
Understanding Activity Streams
The W3C Activity Streams specification is at the core of how ActivityPub works. This format underpins the way the protocol handles social content.
While ActivityPub is best known for short-form text on platforms like Mastodon and Threads, it’s capable of supporting a much wider range of content types. These include:
- Longform text articles (e.g., WordPress.com, Flipboard, Ghost)
- Images (e.g., PixelFed)
- Video (e.g, PeerTube)
- Audio (e.g., Funkwhale)
- Forums (e.g., Lemmy)
In addition to content, Activity Streams handles “actors” in the network too. These are people who can do things, such as people, bots or brands.
But these objects are nothing without social activities to connect them.
“Activities are all the actions that we take in a social network, and those have a representation in the Activity Streams format. So for example, liking something generates a ‘like’ activity, and following someone is a ‘follow’ activity,” Prodromou says.
“We have activities for the full CRUD lifestyle — Create, Read, Update and Delete — as well as activities for adding things to a collection, removing them from a collection, geosocial information, event management, marketplaces… we have a lot of different activities.”
Mapping Your Software to Activity Streams
Prodromou explains that the first step for planning an ActivityPub integration is to figure out how different aspects of your software map to the Activity Streams format.
If you’re building forum software, then maybe forum posts can be mapped to the Article content type in Activity Streams. Maybe the comments of your forum posts could be Notes in Activity Streams (the content type used for short-form text).
“Activity Streams is an extensible vocabulary.”
While this mapping exercise is usually straightforward, Prodromou says that there can be challenges.
“Sometimes there’s not an easy mapping. So if you have, for example, a service for sharing models for 3D printers, we don’t have that built into ActivityPub. It’s not part of the basic standard. However, Activity Streams is an extensible vocabulary.”
This extensible vocabulary, he explains, means you can create new metadata types for your own content if it doesn’t map to existing formats.
Connecting to the Fediverse
Once you’ve mapped out how the various aspects of your social app line up with the ActivityPub standard, you need a RESTful API endpoint for each of them.
For example, other ActivityPub-compatible services will need a way of accessing user information such as name, bio, and picture from your service. Running with this example, Prodromou explains what’s required:
“You need to have input and output endpoints for your users. So if someone sends something to your user, you need to have a POST API endpoint that receives that information, called the user’s inbox. And it’s that inbox [which] is found on their user object. Then the outbox is where any activities that the user generates come out.”
“ActivityPub is not complete, and it may never be complete, because the way that people deal with social networks and social interactions is always changing.”
ActivityPub servers have a number of activities they need to support. These include following; accepting or rejecting a follow; creating, updating or deleting an object; adding something to a collection; removing it from a collection; blocking someone, and undoing any other activity.
“With that small toolset in your inbox handler, all of a sudden you’re participating as a full member of the fediverse,” Prodromou says.
The final thing to be aware of is that requests between AcitivityPub servers are identified using the IETF’s HTTP signatures protocol.
“This is a way that remote servers can send you something and identify what user it comes from,” Prodromou explains. “Your server can prove it really did come from that server, and can check it using public key cryptography… Most standard libraries can handle it.”
Prodromou also advises developers to familiarize themselves with WebFinger, the protocol that provides a simple, uniform identity system across the fediverse.
Common Stumbling Blocks
Prodromou says one aspect of ActivityPub that can prove tricky to developers is the fact that not all servers support all activity types.
For example, if your platform is built around event invitations, Mastodon users won’t see those invitations because Mastodon doesn’t support that kind of activity.
While you can contact the developers of other platforms and encourage them to support your favored activity type, they are under no obligation to do so. Prodromou encourages you to not worry too much, and accept that the diversity of the fediverse makes some incompatibilities inevitable.
“Different servers are going to have different profiles, and it’s okay if not everything gets to every user… It is a constantly evolving network, and there are new kinds of content on the network every day. It’s totally okay if we have different applications on the network, and maybe they don’t quite understand what each other is doing.”
Always include an event handler or queuing handler.
Another issue to be aware of is that delivering content and actions across the federated network can take time, especially if, for example, a particular user has a lot of followers. Prodromou says you should plan for this by including an event handler or queuing handler.
“Smaller applications sometimes don’t build that in, and you really need it for the fediverse… When someone’s loading a form or posting something, it takes too long and it’s going to stall out your UI or whatever. You really need offline handling.”
And finally, you should plan for the reality of the internet, where data doesn’t always get through the first time due to connectivity issues, brief maintenance downtime periods, and the like.
Building retries into your system for when data doesn’t get through the first time is essential for a fediverse application that runs reliably for users.
Looking to the Future
While building with ActivityPub, you should keep in mind that it’s an evolving standard and your users might well expect you to support new features as they’re introduced in the future.
“ActivityPub is not complete, and it may never be complete, because the way that people deal with social networks and social interactions is always changing,” Prodromou explains.
“There are kinds of social interaction on the web today that didn’t exist when we created ActivityPub, and there will be new kinds of interactions on the web 10 years from now that you and I can’t even imagine right now.”
Prodromou says he’s personally currently working on support for end-to-end encrypted messages, a feature that is rapidly becoming a table-stakes feature for messaging apps.
Data portability is another feature in the works for ActivityPub. This would allow a user to move their ‘home’ in the fediverse from, say, Mastodon to Threads, bringing all of their followers, followed accounts, activities, and content with them.
“The idea is really to keep it a living standard, something that is constantly catching up with cool new ways of interacting as human beings,” Prodromou says.
If you want to help shape the future of ActivityPub development and connect with other developers, Prodromou recommends you engage with the Social Web Incubator Community Group and the Fediverse Developer Portal.
Evan Prodromou’s new book ActivityPub: Programming for the Social Web is available now via the O’Reilly learning platform.
