Logo

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 in two steps:

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

Example

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

Example Request

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

Example Response

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

Then, we

  • Pick version 0.6.0 to use
  • 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",
            "0.6.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
}