Skip to content

Commit 92c96bc

Browse files
CPlusPatchCPlusPatch
authored
Merge pull request #75 from versia-pub/feat/v0.6
Feat/v0.6
2 parents fff8542 + 4c7b347 commit 92c96bc

67 files changed

Lines changed: 1845 additions & 1152 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎app/api/basics/page.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
export const metadata = {
2+
title: "API",
3+
description: "Defines the server-to-server API for Versia's federation.",
4+
}
5+
6+
# API
7+
8+
Versia defines a very simple API for server-to-server communication, mainly fetching and sending entities. It is clearly namespaced and versioned, to avoid confusion with implementations' existing HTTP APIs. {{ className: "lead" }}
9+
10+
## API Versioning
11+
12+
Every Versia API endpoint is prefixed with `/.versia/vX/`, where `X` is the version of the API. The current version is `0.6`, so the current API prefix is `/.versia/v0.6/`. This versioning is used to avoid breaking changes in the future, and to allow for backwards compatibility.
13+
14+
Requests not encrypted with TLS (aka HTTPS) **must not** be sent or responded to. All implementations are required to use TLS 1.2 or higher, and to support HTTP/2.
15+
16+
<Note>
17+
Implementations have no obligation to support more than one Versia version. It is recommended to always support the latest version, as it helps avoid bogging down the network with old versions.
18+
</Note>
19+
20+
## Signatures
21+
22+
API requests/responses between instances **must** include a [Signature](/signatures), signed with the [instance's private key](/entities/instance-metadata), as defined in [Signatures](/signatures).
23+
24+
## Encoding
25+
26+
"URL-encoding" is the mechanism used to encode data containing special characters in URLs. When this specification refers to "URL-encoding", it means the encoding defined in [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1).
27+
28+
## Domain
29+
30+
Versia defines a **domain** as the hostname of an instance, which is used to identify the instance in the network. It **must** be a valid hostname, and cannot include a port number (the HTTPS port is always 443).
31+
32+
Defining a domain is very complicated, so please refer to the following examples:
33+
34+
``` {{ "title": "Valid Domains" }}
35+
example.com
36+
test.localhost
37+
sus.example.org
38+
xn--ls8h.la
39+
1.0.1.7.0.8.0.0.0.0.7.4.0.1.0.0.2.ip6.arpa # We know what you did
40+
```
41+
42+
``` {{ "title": "Invalid Domains" }}
43+
example.com:3000 # ❌️ Invalid: port number is not allowed
44+
test..localhost # ❌️ Invalid: double dot is not allowed
45+
example.com. # ❌️ Invalid: trailing dot is not allowed
46+
test.org/ # ❌️ Invalid: trailing slash is not allowed
47+
test.org/sus # ❌️ Invalid: path is not allowed
48+
💩.la # ❌️ Invalid: IDNs must be Punycode encoded
49+
https://bob.org # ❌️ Invalid: protocol is not allowed
50+
```
51+
52+
## Redirects
53+
54+
API endpoints **MUST NOT** redirect to other endpoints, with the following exceptions:
55+
- When the request does not have an `Accept: application/vnd.versia+json` header, the server **MAY** redirect to an HTML representation of the resource.
56+
57+
<Warning>
58+
HTTP to HTTPS redirects are **NOT** allowed for API endpoints.
59+
60+
This is to force all API communication to be encrypted, and to avoid accidentally leaking sensitive data over unencrypted connections.
61+
</Warning>
62+
63+
This is forbidden:
64+
65+
```http
66+
GET /.versia/v0.6/entities/user/1234
67+
Host: example.com
68+
Accept: application/vnd.versia+json
69+
70+
HTTP/1.1 301 Moved Permanently
71+
Location: https://example.com/users/1234
72+
```
73+
74+
This is allowed:
75+
```http
76+
GET /.versia/v0.6/entities/user/1234
77+
Host: example.com
78+
Accept: text/html
79+
80+
HTTP/1.1 301 Moved Permanently
81+
Location: https://example.com/users/1234
82+
```

‎app/api/endpoints/page.mdx‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
export const metadata = {
2+
title: "API Endpoints",
3+
description: "Explains all endpoints in Versia's federation API.",
4+
}
5+
6+
# Endpoints
7+
8+
## Well-known
9+
10+
<Warning>
11+
This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it.
12+
13+
The following `Accept` headers are also allowed for requests to this endpoint:
14+
- `application/jrd+json`
15+
- `application/json`
16+
</Warning>
17+
18+
<Row>
19+
<Col>
20+
21+
<Properties name="Well-known">
22+
<Property name="endpoint">
23+
Must be `/.well-known/versia`.
24+
</Property>
25+
<Property name="method">
26+
Must be `GET`.
27+
</Property>
28+
<Property name="response">
29+
A small JSON object with a single attribute:
30+
31+
- `versions`: Supported Versia Protocol versions.
32+
- Versions marked as "Working Draft X" are represented as `0.X`.
33+
</Property>
34+
</Properties>
35+
36+
</Col>
37+
<Col sticky>
38+
39+
```http {{ 'title': 'Example request' }}
40+
GET /.well-known/versia
41+
Host: b.social
42+
Accept: application/jrd+json
43+
```
44+
45+
```http {{ 'title': 'Example response' }}
46+
HTTP/1.1 200 OK
47+
Content-Type: application/jrd+json
48+
49+
{
50+
"versions": [
51+
"0.6.0",
52+
"0.5.0"
53+
]
54+
}
55+
```
56+
57+
</Col>
58+
</Row>
59+
60+
## Instance metadata
61+
62+
<Warning>
63+
This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it.
64+
</Warning>
65+
66+
<Row>
67+
<Col>
68+
69+
<Properties name="InstanceMetadata">
70+
<Property name="endpoint">
71+
Must be `/.versia/v0.6/instance`.
72+
</Property>
73+
<Property name="method">
74+
Must be `GET`.
75+
</Property>
76+
<Property name="response">
77+
Instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document.
78+
</Property>
79+
</Properties>
80+
81+
</Col>
82+
<Col sticky>
83+
84+
```http {{ 'title': 'Example request' }}
85+
GET /.versia/v0.6/instance
86+
Host: b.social
87+
Accept: application/vnd.versia+json
88+
```
89+
90+
```http {{ 'title': 'Example response' }}
91+
HTTP/1.1 200 OK
92+
Content-Type: application/vnd.versia+json; charset=utf-8
93+
94+
{
95+
"type": "InstanceMetadata",
96+
"name": "Bob!!",
97+
// ...
98+
}
99+
```
100+
101+
</Col>
102+
</Row>
103+
104+
## Entity data
105+
106+
<Row>
107+
<Col>
108+
<Properties name="EntityData">
109+
<Property name="endpoint">
110+
Must be `/.versia/v0.6/entities/{entity_type}/{id}`.
111+
112+
- `{entity_type}`: The type of the entity to fetch, URL-encoded.
113+
- `{id}`: The ID of the entity to fetch, URL-encoded.
114+
115+
Example: `GET /.versia/v0.6/entities/pub.versia%3Agroups%2FGroup/1234` fetches the [Group](/extensions/groups) entity with ID `1234`.
116+
</Property>
117+
<Property name="method">
118+
Must be `GET`.
119+
</Property>
120+
<Property name="response">
121+
Entity data as JSON, as defined in its [Entity](/entities) definition document.
122+
</Property>
123+
</Properties>
124+
</Col>
125+
126+
<Col sticky>
127+
128+
```http {{ 'title': 'Example request' }}
129+
GET /.versia/v0.6/entities/user/1234
130+
Host: b.social
131+
Accept: application/vnd.versia+json
132+
```
133+
134+
```http {{ 'title': 'Example response' }}
135+
HTTP/1.1 200 OK
136+
Content-Type: application/vnd.versia+json; charset=utf-8
137+
138+
{
139+
"type": "User",
140+
"id": "1234",
141+
// ...
142+
}
143+
```
144+
</Col>
145+
</Row>
146+
147+
## Entity collections
148+
149+
<Row>
150+
<Col>
151+
<Properties name="EntityCollection">
152+
<Property name="endpoint">
153+
Must be `/.versia/v0.6/entities/{entity_type}/{id}/collections/{collection_type}`.
154+
155+
- `{entity_type}`: The type of the entity to fetch, URL-encoded.
156+
- `{id}`: The ID of the entity to fetch, URL-encoded.
157+
- `{collection_type}`: The type of the collection to fetch, URL-encoded.
158+
159+
Example: `GET /.versia/v0.6/entities/User/1234/collections/followers` fetches the followers of the user with ID `1234`.
160+
</Property>
161+
<Property name="method">
162+
Must be `GET`.
163+
</Property>
164+
<Property name="response">
165+
Must be either a [Collection](/structures/collection) or a [URICollection](/structures/collection#uri-collection) as JSON.
166+
</Property>
167+
</Properties>
168+
</Col>
169+
170+
<Col sticky>
171+
172+
```http {{ 'title': 'Example request' }}
173+
GET /.versia/v0.6/entities/user/1234/collections/followers
174+
Host: b.social
175+
Accept: application/vnd.versia+json
176+
```
177+
178+
```http {{ 'title': 'Example response' }}
179+
HTTP/1.1 200 OK
180+
Content-Type: application/vnd.versia+json; charset=utf-8
181+
182+
{
183+
"type": "Followers",
184+
"id": "1234",
185+
// ...
186+
}
187+
```
188+
</Col>
189+
</Row>
190+
191+
### Pagination
192+
193+
Collections MUST support pagination, using the following URI parameters:
194+
195+
- `offset`: The number of items to skip before returning the first item. This is a zero-based index.
196+
- `limit`: The maximum number of items to return. This is a one-based index. Implementations MUST support a minimum of `1` and a maximum of `40` items.
197+
198+
```http {{ 'title': 'Example paginated collection request' }}
199+
GET /.versia/v0.6/entities/user/1234/collections/followers?offset=10&limit=20
200+
Host: b.social
201+
Accept: application/vnd.versia+json
202+
```
203+
204+
## Inbox
205+
206+
The inbox endpoint is used for instances to send entities to each other. It is a single endpoint that can receive messages for every user (also known as a shared inbox).
207+
208+
The delivery mechanism is described further in the [Federation](/federation#inboxes) document.
209+
210+
<Row>
211+
<Col>
212+
<Properties name="Inbox">
213+
<Property name="endpoint">
214+
Must be `/.versia/v0.6/inbox`.
215+
</Property>
216+
<Property name="method">
217+
Must be `POST`.
218+
</Property>
219+
</Properties>
220+
</Col>
221+
222+
<Col sticky>
223+
224+
```http {{ 'title': 'Example request' }}
225+
POST /.versia/v0.6/inbox
226+
Host: b.social
227+
Accept: application/vnd.versia+json
228+
Content-Type: application/vnd.versia+json; charset=utf-8
229+
230+
{
231+
"type": "Note",
232+
"id": "1234",
233+
...
234+
}
235+
```
236+
237+
</Col>
238+
</Row>

‎app/changelog/page.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,27 @@ export const metadata = {
88

99
This page lists changes since Working Draft 3. {{ className: 'lead' }}
1010

11+
## Since WD 5
12+
13+
- Added a new `content-type` for Versia entities: `application/vnd.versia+json`.
14+
- Overhauled the Instance-to-Instance API to have clearly defined and namespaced endpoints, under `/.versia/v0.6/`, instead of letting implementations define their own endpoints.
15+
- Removed per-User keypairs: now, only the instance keypair is used for signing.
16+
- Moved [Delegation](/extensions/delegation) to an extension
17+
- Changed the contents of the [Well-Known Versia Endpoint](/api/endpoints#well-known) to only list supported protocol versions.
18+
- Modified how URIs and references to other entities are handled:
19+
- The `uri` field has been removed from all entities.
20+
- Every field that used to be a URI now uses that entity's `id` field.
21+
- New endpoints have been defined under `/.versia/v0.6/` to fetch entities by their `id`.
22+
- Added [References](/types#reference) as a way to refer to other entities.
23+
- Changed usage of "`null` authors" to simply being an optional field.
24+
- Added more guidelines on [JSON data handling](/json).
25+
- Clarified the meaning of [Domain](/api/basics#domain) in the context of Versia.
26+
- Changes to [Note](/entities/note):
27+
- `is_sensitive`, `attachments`, `mentions` and `previews` are now required.
28+
- Changes to [User](/entities/user):
29+
- `fields`, `manually_approves_followers` and `indexable` are now required.
30+
- Removed "short pronoun" from [Vanity Extension](/extensions/vanity) (union types are tricky to parse in strongly typed languages).
31+
1132
## Since WD 4
1233

1334
- Removed URI from [Report](/extensions/reports), and replaced `reason` with `tags`.

0 commit comments

Comments
 (0)