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

See the Inbox Endpoint for more information on the inbox endpoint.

Ever Instance has a personal HTTP endpoint called an inbox (/.versia/v0.6/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 instance's inbox endpoint. 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.

Outboxes

In addition to inboxes, every user has an outbox (at /.versia/v0.6/entities/User/<id>/collections/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.

Implementations should filter out entities that are not relevant to the request author when returning the outbox.

For example, if Alice sends a Note to Bob on direct visibility:

Alice's instance should return the Note in response to a request from Bob's instance.
Alice's instance should not display the Note in her outbox in response to a request from Joe's instance.

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.