feat: ✨ Document basics of S2S Federation API, and some endpoints

2026-03-13 10:59:16 +01:00 · 2025-05-01 20:09:59 +02:00 · 2025-05-01 20:09:59 +02:00 · 71064dea2c
commit 71064dea2c
parent 3f94eff3e3
6 changed files with 187 additions and 0 deletions
--- a/app/api/endpoints/page.mdx
+++ b/app/api/endpoints/page.mdx
@ -0,0 +1,150 @@
+export const metadata = {
+    title: "API Endpoints",
+    description: "Explains all endpoints in Versia's federation API.",
+}
+
+# Endpoints
+
+## Instance metadata
+
+<Warning>
+    This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it.
+</Warning>
+
+<Row>
+  <Col>
+
+    <Properties name="InstanceMetadata">
+        <Property name="endpoint">
+            Must be `/.versia/v0.6/instance`.
+        </Property>
+        <Property name="method">
+            Must be `GET`.
+        </Property>
+        <Property name="response">
+            Must be the instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document.
+        </Property>
+    </Properties>
+
+  </Col>
+  <Col sticky>
+
+    ```http {{ 'title': 'Example request' }}
+    GET /.versia/v0.6/instance
+    Host: b.social
+    Accept: application/vnd.versia+json
+    ```
+    
+    ```http {{ 'title': 'Example response' }}
+    HTTP/1.1 200 OK
+    Content-Type: application/vnd.versia+json
+
+    {
+        "type": "InstanceMetadata",
+        "name": "Bob!!",
+        // ...
+    }
+    ```
+
+  </Col>
+</Row>
+
+## Entity data
+
+<Row>
+    <Col>
+        <Properties name="EntityData">
+            <Property name="endpoint">
+                Must be `/.versia/v0.6/entities/{entity_type}/{id}`.
+
+                - `{entity_type}`: The type of the entity to fetch, URL-encoded.
+                - `{id}`: The ID of the entity to fetch, URL-encoded.
+
+                Example: `GET /.versia/v0.6/entities/pub.versia%3Agroups%2FGroup/1234` fetches the [Group](/extensions/groups) entity with ID `1234`.
+            </Property>
+            <Property name="method">
+                Must be `GET`.
+            </Property>
+            <Property name="response">
+                Must be the entity's data as JSON, as defined in its [Entity](/entities) definition document.
+            </Property>
+        </Properties>
+    </Col>
+
+    <Col sticky>
+
+        ```http {{ 'title': 'Example request' }}
+        GET /.versia/v0.6/entities/user/1234
+        Host: b.social
+        Accept: application/vnd.versia+json
+        ```
+
+        ```http {{ 'title': 'Example response' }}
+        HTTP/1.1 200 OK
+        Content-Type: application/vnd.versia+json
+
+        {
+            "type": "User",
+            "id": "1234",
+            // ...
+        }
+        ```
+    </Col>
+</Row>
+
+## Entity collections
+
+<Row>
+    <Col>
+        <Properties name="EntityCollection">
+            <Property name="endpoint">
+                Must be `/.versia/v0.6/entities/{entity_type}/{id}/collections/{collection_type}`.
+
+                - `{entity_type}`: The type of the entity to fetch, URL-encoded.
+                - `{id}`: The ID of the entity to fetch, URL-encoded.
+                - `{collection_type}`: The type of the collection to fetch, URL-encoded.
+
+                Example: `GET /.versia/v0.6/entities/User/1234/collections/followers` fetches the followers of the user with ID `1234`.
+            </Property>
+            <Property name="method">
+                Must be `GET`.
+            </Property>
+            <Property name="response">
+                Must be either a [Collection](/structures/collection) or a [URICollection](/structures/collection#uri-collection) as JSON.
+            </Property>
+        </Properties>
+    </Col>
+
+    <Col sticky>
+
+        ```http {{ 'title': 'Example request' }}
+        GET /.versia/v0.6/entities/user/1234/collections/followers
+        Host: b.social
+        Accept: application/vnd.versia+json
+        ```
+
+        ```http {{ 'title': 'Example response' }}
+        HTTP/1.1 200 OK
+        Content-Type: application/vnd.versia+json
+
+        {
+            "type": "Followers",
+            "id": "1234",
+            // ...
+        }
+        ```
+    </Col>
+</Row>
+
+### Pagination
+
+Collections MUST support pagination, using the following URI parameters:
+
+- `offset`: The number of items to skip before returning the first item. This is a zero-based index.
+- `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.
+
+```http {{ 'title': 'Example paginated collection request' }}
+GET /.versia/v0.6/entities/user/1234/collections/followers?offset=10&limit=20
+Host: b.social
+Accept: application/vnd.versia+json
+```