mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 22:38:19 +01:00
78 lines
2.5 KiB
Plaintext
78 lines
2.5 KiB
Plaintext
|
export const metadata = {
|
||
|
|
title: 'Discovery',
|
||
|
|
description: "How Versia instances can discover users, capabilities, and endpoints.",
|
||
|
|
}
|
||
|
|
|
||
|
|
# 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](/entities/user#addresses). Knowing this, the [WebFinger](https://tools.ietf.org/html/rfc7033) 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`.
|
||
|
|
|
||
|
|
```http {{ 'title': 'Example Request' }}
|
||
|
|
GET /.well-known/webfinger?resource=acct:george@versia.social HTTP/1.1
|
||
|
|
Accept: application/jrd+json
|
||
|
|
```
|
||
|
|
|
||
|
|
```jsonc {{ 'title': 'Example Response' }}
|
||
|
|
{
|
||
|
|
"subject": "acct:george@versia.social", // [!code focus:6]
|
||
|
|
"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"
|
||
|
|
},
|
||
|
|
{ // [!code focus:5]
|
||
|
|
"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"
|
||
|
|
}
|
||
|
|
] // [!code focus]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Server Discovery
|
||
|
|
|
||
|
|
Server metadata can be accessed by making a `GET` request to the server's Versia metadata endpoint, which is located at `/.well-known/versia`.
|
||
|
|
|
||
|
|
### Example
|
||
|
|
|
||
|
|
To discover the metadata of the server `versia.social`, an instance would make a `GET` request to `https://versia.social/.well-known/versia`.
|
||
|
|
|
||
|
|
This endpoint will return a [ServerMetadata](/entities/server-metadata) entity.
|
||
|
|
|
||
|
|
```http {{ 'title': 'Example Request' }}
|
||
|
|
GET /.well-known/versia HTTP/1.1
|
||
|
|
Accept: application/json
|
||
|
|
```
|
||
|
|
|
||
|
|
```jsonc {{ 'title': 'Example Response' }}
|
||
|
|
{
|
||
|
|
"type": "ServerMetadata",
|
||
|
|
"name": "Versia Social",
|
||
|
|
"uri": "https://versia.social",
|
||
|
|
"version": "3.2.0",
|
||
|
|
"supported_extensions": [
|
||
|
|
"org.lysand:reactions",
|
||
|
|
"org.lysand:polls",
|
||
|
|
"org.lysand:custom_emojis",
|
||
|
|
"org.lysand:is_cat"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
```
|