Federation

Being a federation protocol, Versia defines a set of rules for exchanging data between instances. This document outlines the behavior of instances in a Versia federated network.

Federation is built on the HyperText Transfer Protocol (HTTP) and the JavaScript Object Notation (JSON) data format. Instances communicate with each other by sending and receiving JSON payloads over HTTP. If you have ever worked with ActivityPub, Versia's federation protocol will feel familiar.

Guides

HTTP Guidelines

Guidelines for HTTP communication in Versia.

Validation

Validation rules for Versia implementations.

Discovery

How Versia instances can discover users, capabilities, and endpoints.

Delegation

Authorizing actions on behalf of another user.

Inboxes

Ever User has a personal HTTP endpoint called an inbox (e.g., /users/3/inbox). This endpoint is used to send and receive messages between users and instances. Messages are sent as JSON payloads over HTTP POST requests.

Let's consider the following example:

Alice, on the instance alice.example, sends a message to Bob on the instance bob.example.

To perform this action, Alice's instance sends a POST request to Bob's inbox endpoint, which can be found by checking the inbox field in Bob's User entity. This request contains the Note entity that Alice wants to send to Bob, with the appropriate metadata to ensure the message is valid.

Bob's instance receives the message and processes it according to the rules defined in the Validation document.

Shared Inboxes

In addition to personal inboxes, instances can also have shared inboxes. Shared inboxes are a single per-instance endpoint that can receive messages for multiple users. This is useful for instances that want to reduce the number of HTTP requests they need to handle.

Shared inboxes are defined in the Instance Metadata entity. If supported, they should be used in place of personal inboxes.

Outboxes

In addition to inboxes, every user has an outbox (e.g., /users/3/outbox). The outbox is simply a collection of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox.

Outboxes are very useful for "backfilling" data when a new instance joins the network. By resolving the outboxes of all new users it encounters, a new instance can quickly catch up on all old messages.