Discovery

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

User Discovery

To discover a user, an instance must know the user's address. Knowing this, the WebFinger protocol can be used to find the user's profile.

Example

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

Example Request

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

Example Response

{
    "subject": "acct:george@versia.social", 
    "aliases": [
        "https://versia.social/.versia/v0.6/entities/User/018ec082-0ae1-761c-b2c5-22275a611771",
        "https://versia.social/@george"
    ],
    "links": [
        {
            "rel": "http://webfinger.net/rel/profile-page",
            "type": "text/html",
            "href": "https://versia.social/@george"
        },
        { 
            "rel": "self",
            "type": "application/vnd.versia+json",
            "href": "https://versia.social/.versia/v0.6/entities/User/018ec082-0ae1-761c-b2c5-22275a611771"
        },
        {
            "rel": "http://webfinger.net/rel/avatar",
            "type": "image/png",
            "href": "https://cdn.versia.social/uploads/banana.png"
        }
    ] 
}

Instance Discovery

Instance metadata can be accessed by making a GET request to the instance's Versia metadata endpoint, documented in the Endpoints document.

Example

To discover the metadata of the instance versia.social, an instance would make a GET request to https://versia.social/.versia/v0.6/instance.

This endpoint will return an InstanceMetadata entity.

Example Request

GET /.versia/v0.6/instance HTTP/1.1
Accept: application/vnd.versia+json

Example Response

{
    "type": "InstanceMetadata",
    "name": "Versia Social",
    "software": {
        "name": "Versia Server",
        "version": "0.7.0"
    },
    "compatibility": {
        "versions": [
            "0.5.0"
        ],
        "extensions": [
            "pub.versia:reactions",
            "pub.versia:polls",
            "pub.versia:reports"
        ]
    },
    "domain": "versia.social",
    "created_at": "2021-07-01T00:00:00Z",
    "description": null,
    "logo": null,
    "banner": null
}