BookWyrm uses the ActivityPub protocol to send and receive user activity between other BookWyrm instances and other services that implement ActivtyPub, like Mastodon. To handle book data, BookWyrm has a handful of extended Activity types which are not part of hte standard, but are legible to other BookWyrm instances.

Activities and ObjectsHyperlink to this header

Users and relationshipsHyperlink to this header

User relationship interactions follow the standard ActivityPub spec.

  • Follow: request to receive statuses from a user, and view their statuses that have followers-only privacy
  • Accept: approves a Follow and finalizes the relationsip
  • Reject: denies a Follow
  • Block: prevent users from seeing one another's statuses, and prevents the blocked user from viewing the actor's profile
  • Update: updates a user's profile and settings
  • Delete: deactivates a user
  • Undo: reverses a Follow or Block

StatusesHyperlink to this header

Object typesHyperlink to this header

  • Note: On services like Mastodon, Notes are the primary type of status. They contain a message body, attachments, can mention users, and be replies to statuses of any type. Within BookWyrm, Notes can only be created as direct messages or as replies to other statuses.
  • Review: A review is a status in repsonse to a book (indicated by the inReplyToBook field), which has a title, body, and numerical rating between 0 (not rated) and 5.
  • Comment: A comment on a book mentions a book and has a message body.
  • Quotation: A quote has a message body, an excerpt form a book, and mentions a book

ActivitiesHyperlink to this header

  • Create: saves a new status in the database.

Note: BookWyrm only accepts Create activities if they are:

  • Direct messages (ie, Notes with the privacy level direct, which mention a local user),
  • Related to a book (of a custom status type that includes the field inReplyToBook),
  • Replies to existing statuses saved in the database
  • Delete: Removes a status
  • Like: Creates a favorite on the status
  • Announce: Boosts the status into the actor's timeline
  • Undo: REverses a Like or Announce

CollectionsHyperlink to this header

User's books and lists are represented by OrderedCollection

ObjectsHyperlink to this header

  • Shelf: A user's book collection. By default, every user has to-read, reading, and read shelf which are used to track reading progress.
  • List: A collection of books that may have items contributed besides the user who created the list.

ActivitiesHyperlink to this header

  • Create: Adds a shelf or list to the database.
  • Delete: Removes a shelf or list.
  • Add: Adds a book to a shelf or list.
  • Remove: Removes a book from a shelf or list.

Alternative SerializationHyperlink to this header

Because BookWyrm uses custom object types (Review, Comment, Quotation) that aren't supported by ActivityPub, statues are transformed into standard types when sent to or viewed by non-BookWyrm services. Reviews are converted into Articles, and Comments and Quotations are converted into Notes, with a link to the book and the cover image attached.