Discovery

A lot of the time, Versia instances may need to look up information about other instances, such as their users, capabilities, and public keys. This is done through a process called discovery.

User Discovery

Discovering a user starts from the user’s address. With it, the WebFinger protocol can be used to find the user’s profile.

User Discovery Example

To discover the profile of the user @george@versia.example, an instance would make a GET request to https://versia.example/.well-known/webfinger?resource=acct:george@versia.example.

GET /.well-known/webfinger?resource=acct:george@versia.example HTTP/1.1
Host: versia.example
Accept: application/jrd+json

{
    "subject": "acct:george@versia.example",
    "aliases": [
        "https://versia.example/.versia/v0.7/entities/User/033p0g85e2000",
        "https://versia.example/@george"
    ],
    "links": [
        {
            "rel": "http://webfinger.net/rel/profile-page",
            "type": "text/html",
            "href": "https://versia.example/@george"
        },
        {
            "rel": "self",
            "type": "application/vnd.versia+json",
            "href": "https://versia.example/.versia/v0.7/entities/User/033p0g85e2000"
        },
        {
            "rel": "http://webfinger.net/rel/avatar",
            "type": "image/png",
            "href": "https://cdn.example.com/uploads/banana.png"
        }
    ]
}

Instance Discovery

Instance metadata can be accessed in two steps:

1. Making a GET request to the instance’s /.well-known/versia endpoint to discover supported Versia Protocol versions.
2. Choosing the protocol version to use, and then querying the instance metadata endpoint as documented in the Endpoints document.

Instance Discovery Example

To discover the metadata of the instance versia.example, an instance would first make a GET request to https://versia.example/.well-known/versia.

GET /.well-known/versia HTTP/1.1
Host: versia.example
Accept: application/json

{
    "versions": [
        "0.7.0",
        "0.6.0"
    ]
}

Then, it:

• Picks 0.7, the highest 0.X that both instances support
• Makes a GET request to https://versia.example/.versia/v0.7/instance.

This endpoint will return an InstanceMetadata entity.

GET /.versia/v0.7/instance HTTP/1.1
Host: versia.example
Accept: application/vnd.versia+json

{
    "type": "InstanceMetadata",
    "name": "Example Instance",
    "software": {
        "name": "Versia Server",
        "version": "0.7.0"
    },
    "compatibility": {
        "extensions": [
            "pub.versia:social@1",
            "pub.versia:reactions@1",
            "pub.versia:polls@1",
            "pub.versia:reports@1"
        ]
    },
    "domain": "versia.example",
    "public_key": {
        "algorithm": "ed25519",
        "key": "MCowBQYDK2VwAyEA9zhEMtQZetRl4QrLcz99i7jOa6ZVjX7aLfRUsMuKByI="
    },
    "created_at": "2021-07-01T00:00:00Z"
}