mirror of
https://github.com/versia-pub/docs.git
synced 2026-03-13 02:49:16 +01:00
refactor: 📝 Update all extension to remove now-useless fields
This commit is contained in:
Jesse Wierzbinski
parent
51c53824ad
commit
d886b83e62
27 changed files with 166 additions and 410 deletions
|
|
@ -49,17 +49,17 @@ Accept: application/jrd+json
|
|||
|
||||
## 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.
|
||||
Instaance metadata can be accessed by making a `GET` request to the instance's Versia metadata endpoint, documented in the [Endpoints](/api/endpoints#instance-metadata) document.
|
||||
|
||||
### Example
|
||||
|
||||
To discover the metadata of the instance `versia.social`, an instance would make a `GET` request to `https://versia.social/.well-known/versia`.
|
||||
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](/entities/instance-metadata) entity.
|
||||
|
||||
```http {{ 'title': 'Example Request' }}
|
||||
GET /.well-known/versia HTTP/1.1
|
||||
Accept: application/json
|
||||
GET /.versia/v0.6/instance HTTP/1.1
|
||||
Accept: application/vnd.versia+json
|
||||
```
|
||||
|
||||
```jsonc {{ 'title': 'Example Response' }}
|
||||
|
|
|
|||
|
|
@ -40,8 +40,8 @@ curl https://b.social/.well-known/webfinger?resource=acct:joe@b.social -H "Accep
|
|||
"links": [
|
||||
{ // [!code focus:5]
|
||||
"rel": "self",
|
||||
"type": "application/json",
|
||||
"href": "https://b.social/users/joe"
|
||||
"type": "application/vnd.versia+json",
|
||||
"href": "https://b.social/.versia/entities/User/joe"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -58,12 +58,12 @@ curl https://b.social/.well-known/webfinger?resource=acct:joe@b.social -H "Accep
|
|||
`a.social` fetches the user profile of `joe` from `b.social` using the URL provided in the WebFinger response.
|
||||
|
||||
```bash
|
||||
curl https://b.social/users/joe \
|
||||
-H "Accept: application/json" \
|
||||
curl https://b.social/.versia/entities/User/joe \
|
||||
-H "Accept: application/vnd.versia+json" \
|
||||
-H "User-Agent: CoolServer/1.0 (https://coolserver.com)" \
|
||||
# The request is signed by a.social's instance private key
|
||||
-H "Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==" \
|
||||
-H "Versia-Signed-By: https://a.social/users/alice" \
|
||||
-H "Versia-Signed-By: a.social" \
|
||||
-H "Versia-Signed-At: 1729241687"
|
||||
```
|
||||
|
||||
|
|
@ -79,13 +79,8 @@ curl https://b.social/users/joe \
|
|||
"content": "https://cdn.b.social/avatars/joe.webp",
|
||||
"remote": true
|
||||
}
|
||||
}, // [!code focus:8]
|
||||
}, // [!code focus:3]
|
||||
"display_name": "Joe Swanson (Winter Arc :gigachad:)",
|
||||
"public_key": {
|
||||
"actor": "b.social:bde22zi3ca8762",
|
||||
"algorithm": "ed25519",
|
||||
"key": "MCowBQYDK2VwAyEAOSCcfsde0Ya3vf/P6lzgK0pA8qCISqneaze3omLlQCQ="
|
||||
},
|
||||
"username": "joe",
|
||||
"extensions": {
|
||||
"pub.versia:custom_emojis": {
|
||||
|
|
@ -142,13 +137,13 @@ It is now time for `a.social` to send the note to `joe`.
|
|||
`a.social` sends the note to `joe`'s inbox at `b.social`.
|
||||
|
||||
```bash
|
||||
curl -X POST https://b.social/inbox \
|
||||
-H "Content-Type: application/json; charset=utf-8" \
|
||||
curl -X POST https://b.social/.versia/v0.6/inbox \
|
||||
-H "Content-Type: application/vnd.versia+json; charset=utf-8" \
|
||||
-H "Accept: application/json" \
|
||||
-H "User-Agent: CoolerServer/1.0 (https://coolerserver.com)" \
|
||||
# The request is signed by Alice's private key
|
||||
-H "Versia-Signature: 9BrfplAPVH6OEqlV5eX7MazaZAInSCPODZcBEvMliBi/OwfbCAsezlb0O9jUX9ZcbBA68ThA4WUgS9V+42rfAQ==" \
|
||||
-H "Versia-Signed-By: https://a.social/users/alice" \
|
||||
-H "Versia-Signed-By: a.social" \
|
||||
-H "Versia-Signed-At: 1733051946"
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -16,10 +16,10 @@ ALL kinds of HTTP requests/responses between instances **MUST** include a [Signa
|
|||
<Col>
|
||||
<Properties name="HTTP Request">
|
||||
<Property name="Accept" type="string" required={true}>
|
||||
Must include `application/json`.
|
||||
Must include `application/vnd.versia+json`, unless specified otherwise.
|
||||
</Property>
|
||||
<Property name="Content-Type" type="string" required={true}>
|
||||
Must include `application/json; charset=utf-8`, if the request has a body.
|
||||
Must include `application/vnd.versia+json; charset=utf-8`, if the request has a body.
|
||||
</Property>
|
||||
<Property name="Versia-Signature" type="string" required={false}>
|
||||
See [Signatures](/signatures) for more information.
|
||||
|
|
@ -37,11 +37,12 @@ ALL kinds of HTTP requests/responses between instances **MUST** include a [Signa
|
|||
</Col>
|
||||
<Col sticky>
|
||||
```http {{ 'title': 'Example Request' }}
|
||||
POST https://bob.com/users/1/inbox HTTP/1.1
|
||||
POST https://bob.com/.versia/v0.6/inbox HTTP/1.1
|
||||
# This specific endpoint returns plain JSON
|
||||
Accept: application/json
|
||||
User-Agent: CoolServer/1.0 (https://coolserver.com)
|
||||
Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==
|
||||
Versia-Signed-By: https://example.com/users/1
|
||||
Versia-Signed-By: example.com
|
||||
Versia-Signed-At: 1729241687
|
||||
```
|
||||
</Col>
|
||||
|
|
@ -63,7 +64,7 @@ IETF draft [draft-polli-ratelimit-headers-02](https://www.ietf.org/archive/id/dr
|
|||
<Col>
|
||||
<Properties name="HTTP Response">
|
||||
<Property name="Content-Type" type="string" required={true}>
|
||||
Must include `application/json; charset=utf-8`.
|
||||
Must include `application/vnd.versia+json; charset=utf-8`, unless specified otherwise.
|
||||
</Property>
|
||||
<Property name="Versia-Signature" type="string" required={false}>
|
||||
See [Signatures](/signatures) for more information.
|
||||
|
|
@ -79,9 +80,9 @@ IETF draft [draft-polli-ratelimit-headers-02](https://www.ietf.org/archive/id/dr
|
|||
<Col sticky>
|
||||
```http {{ 'title': 'Example Response' }}
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=utf-8
|
||||
Content-Type: application/vnd.versia+json; charset=utf-8
|
||||
Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==+7BvnWKITyGyTwHbb6fVYwRx1I
|
||||
Versia-Signed-By: https://example.com/users/1
|
||||
Versia-Signed-By: example.com
|
||||
Versia-Signed-At: 1729241717
|
||||
```
|
||||
</Col>
|
||||
|
|
|
|||
|
|
@ -21,24 +21,22 @@ Federation is built on the [HyperText Transfer Protocol (HTTP)](https://tools.ie
|
|||
|
||||
## Inboxes
|
||||
|
||||
Ever [User](/entities/user) has a personal HTTP endpoint called an inbox (e.g., `/users/3/inbox`). This endpoint is used to send and receive messages between users and instances. Messages are sent as JSON payloads over HTTP `POST` requests.
|
||||
<Note>
|
||||
See the [Inbox Endpoint](/api/endpoints#inbox) for more information on the inbox endpoint.
|
||||
</Note>
|
||||
|
||||
Ever [Instance](/entities/instance-metadata) has a personal HTTP endpoint called an inbox (`/.versia/v0.6/inbox`). This endpoint is used to send and receive messages between users and instances. Messages are sent as JSON payloads over HTTP `POST` requests.
|
||||
|
||||
Let's consider the following example:
|
||||
|
||||
> Alice, on the instance `alice.example`, sends a message to Bob on the instance `bob.example`.
|
||||
|
||||
To perform this action, Alice's instance sends a `POST` request to Bob's inbox endpoint, which can be found by checking the `inbox` field in Bob's [User](/entities/user) entity. This request contains the [Note](/entities/note) entity that Alice wants to send to Bob, with [the appropriate metadata](/federation/http) to ensure the message is valid.
|
||||
To perform this action, Alice's instance sends a `POST` request to Bob's instance's inbox endpoint. This request contains the [Note](/entities/note) entity that Alice wants to send to Bob, with [the appropriate metadata](/federation/http) to ensure the message is valid.
|
||||
|
||||
Bob's instance receives the message and processes it according to the rules defined in the [Validation](/federation/validation) document.
|
||||
|
||||
### Shared Inboxes
|
||||
|
||||
In addition to personal inboxes, instances can also have shared inboxes. Shared inboxes are a single per-instance endpoint that can receive messages for multiple users. This is useful for instances that want to reduce the number of HTTP requests they need to handle.
|
||||
|
||||
Shared inboxes are defined in the [Instance Metadata](/entities/instance-metadata) entity. If supported, they should be used in place of personal inboxes.
|
||||
|
||||
## Outboxes
|
||||
|
||||
In addition to inboxes, every user has an outbox (e.g., `/users/3/outbox`). The outbox is simply a [Collection](/structures/collection) of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox.
|
||||
In addition to inboxes, every user has an outbox (at `/.versia/v0.6/entities/User/<id>/collections/outbox`). The outbox is simply a [Collection](/structures/collection) of all the messages that a user has sent. When a user sends a message to another user, a copy of that message is accessible in the sender's outbox.
|
||||
|
||||
Outboxes are very useful for "backfilling" data when a new instance joins the network. By resolving the outboxes of all new users it encounters, a new instance can quickly catch up on all old messages.
|
||||
Loading…
Add table
Add a link
Reference in a new issue