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 @[email protected]
, an instance would make a GET
request to https://versia.social/.well-known/webfinger?resource=acct:[email protected]
.
Example Request
GET /.well-known/webfinger?resource=acct:[email protected] HTTP/1.1
Accept: application/jrd+json
Example Response
{
"subject": "acct:[email protected]",
"aliases": [
"https://versia.social/users/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/json",
"href": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771"
},
{
"rel": "http://webfinger.net/rel/avatar",
"type": "image/png",
"href": "https://cdn.versia.social/uploads/banana.png"
}
]
}
Instance Discovery
Instaance metadata can be accessed by making a GET
request to the instance's Versia metadata endpoint, which is located at /.well-known/versia
. This endpoint does not need any signatures in the output.
Example
To discover the metadata of the instance versia.social
, an instance would make a GET
request to https://versia.social/.well-known/versia
.
This endpoint will return an InstanceMetadata entity.
Example Request
GET /.well-known/versia HTTP/1.1
Accept: application/json
Example Response
{
"type": "InstanceMetadata",
"name": "Versia Social",
"software": {
"name": "Versia Server",
"version": "0.7.0"
},
"compatibility": {
"versions": [
"0.4.0"
],
"extensions": [
"pub.versia:reactions",
"pub.versia:polls",
"pub.versia:reports"
]
},
"host": "versia.social",
"created_at": "2021-07-01T00:00:00Z"
}