About Activipy

What is ActivityStreams? How might it help me?

Activipy is a simple library which makes working with ActivityStreams easy. Which is a bit confusing, because ActivityStreams is already dead-easy. Activipy helps us make things a bit more robust.

How easy is ActivityStreams? Here’s a valid ActivityStreams document from a mad scientist type person:

{"@id": "http://drboss.example/api/objects/123415/",
 "@type": "Create",
 "actor": {
     "@type": "Person",
     "@id": "http://drboss.example/me/",
     "displayName": "Professor BossManager"},
 "to": ["http://employeemine.example/jim/",
        "http://employeemine.example/sarah/"],
 "object": {
     "@type": "Note",
     "@id": "http://drboss.example/rants/power-productivity/",
     "content": "Thanks to my latest invention, productivity is up 1 million percent! MWAHAHA!!"}}

Here’s another:

{"@id": "http://employeemine.example/sarah/blog/new-job-please/"
 "@type": "Note",
 "displayName": "New job, please.",
 "content": "Anyone know where I can get a job not managed by a mad scientist?"}

These objects aren’t complex, and anyone can read them. They’re just JSON, plus some common vocabulary, including a convention that “@id” is the identifier of the object and “@type” is the vocabulary type. That’s pretty simple!

And simple is good, because let’s face it, most users of most web application APIs are like poor Billy Scripter, a kid who has some scripting language like Ruby or Python or Javascript and some JSON parser in a toolbox and that’s about it. Billy Scripter knows how to parse JSON pulled down from some endpoint, and that’s about all he knows how to do. Poor Billy Scripter! But it’s okay, because ActivityStreams is simple enough that Billy can make it by. And because the ActivityStreams Core serialization specifies that the ActivityStreams Vocabulary is always implied and that those terms must always be available, Billy will always know what a Like object or a Note means. Horray for Billy!

Meanwhile, you get the benefit of a well thought out “subject, predicate, object” type structure (or in other words, “who did what”). The Core Classes provide the basic structure, and that general structure combined with the very minimal rules of ActivityStreams Core (roughly speaking, it’s just JSON with the ActivityStreams vocabulary implied, but if you need anything more, you can use json-ld) means that you already have the general structure of all the “social” type activities that happen on the modern web. Throw in the Extended Classes and you’ve got all the right language to express what your users are doing too. Awesome.

But hey, what happens when the base ActivityStreams vocabulary just isn’t enough? Maybe you’re running a social network that’s also a game and you need some way to express that your players are beating up goblins (wait, I take that back, don’t beat up poor goblins!), or you’ve got a highly interactive e-commerce site where users can share coupons or whatever. Look, whatever it is, you can express it in ActivityStreams!

Yeah, I said it! Sure, ActivityStreams gives you almost everything you need out of the box, but if you need to get fancy and define your own terms, you can do that too. ActivityStreams is technically a json-ld document with an implied vocabulary, but you can add on new vocabularies too. Need to add Coupon objects, or RpgBeatemup activities? Yeah, you can do it! And for all you RDF fans out there, you can transform ActivityStreams objects into a full-on linked-data graph. Go wild!

But you also don’t have to. Thanks to the promises made by the ActivityStreams serialization, Billy Scripter can make it by just fine with his Ruby and JSON toolkit. And so can most of the rest of the web!

How Activipy and ActivityStreams work together

So if ActivityStreams is just JSON (and optionally json-ld), what do you need Activipy for? Good question!

Activipy provides a whole suite of useful tools, including friendly and Pythonic constructors, a flexible and extensible method dispatch system, and much more. We could express the above like this:

>>> from activipy import vocab
>>> vocab.Create(
...   "http://drboss.example/api/objects/123415/",
...   actor=vocab.Person(
...     "http://drboss.example/me/",
...     displayName="Professor BossManager"),
...   to=["http://employeemine.example/jim/",
...       "http://employeemine.example/sarah/"],
...   object=vocab.Note(
...     http://drboss.example/rants/power-productivity/",
...     content="Thanks to my latest invention, productivity is up 1 million percent! MWAHAHA!!"))

If we were writing our own diary application, we could specify an environment that knows how to post notes to it:

>>> from ourjournal import DiaryEnv
>>> dear_diary = DiaryEnv.c.Note(
...     displayName="New job, please.",
...     content="Anyone know where I can get a job not managed by a mad scientist?")
>>> dear_diary.m.post()

Activipy provides you with the basic tools you need to map ActivityStreams to the world of your Python application. And if you’re just starting out in writing a brand new social network application? You’d better believe Activipy is a good place to start!

Activipy means making your networked application social is easy. And best of all, you can speak a common language with other ActivityStreams speaking applications across the net.

Sound good? Let’s get started!