From 71064dea2c206e827b619392bd017648eb649472 Mon Sep 17 00:00:00 2001 From: Jesse Wierzbinski Date: Thu, 1 May 2025 20:09:59 +0200 Subject: [PATCH] feat: :sparkles: Document basics of S2S Federation API, and some endpoints --- app/api/basics/page.mdx | 27 +++++++ app/api/endpoints/page.mdx | 150 +++++++++++++++++++++++++++++++++++ app/api/errors/page.mdx | 0 app/api/html/page.mdx | 0 app/api/rate-limits/page.mdx | 0 components/Navigation.tsx | 10 +++ 6 files changed, 187 insertions(+) create mode 100644 app/api/basics/page.mdx create mode 100644 app/api/endpoints/page.mdx create mode 100644 app/api/errors/page.mdx create mode 100644 app/api/html/page.mdx create mode 100644 app/api/rate-limits/page.mdx diff --git a/app/api/basics/page.mdx b/app/api/basics/page.mdx new file mode 100644 index 0000000..851029f --- /dev/null +++ b/app/api/basics/page.mdx @@ -0,0 +1,27 @@ +export const metadata = { + title: "API", + description: "Defines the server-to-server API for Versia's federation.", +} + +# API + +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" }} + +## API Versioning + +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. + + + Implementations have no obligations 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. + + +## Signatures + +- All API requests **MUST** be signed, unless otherwise specified. This includes `POST` and `GET` requests. +- All API responses **MUST** be signed, unless otherwise specified. + +The signature mechanism is defined in the [Signatures](/signatures) document. + +## Encoding + +"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). \ No newline at end of file diff --git a/app/api/endpoints/page.mdx b/app/api/endpoints/page.mdx new file mode 100644 index 0000000..c88012f --- /dev/null +++ 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 + + + This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it. + + + + + + + + Must be `/.versia/v0.6/instance`. + + + Must be `GET`. + + + Must be the instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document. + + + + + + + ```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!!", + // ... + } + ``` + + + + +## Entity data + + + + + + 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`. + + + Must be `GET`. + + + Must be the entity's data as JSON, as defined in its [Entity](/entities) definition document. + + + + + + + ```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", + // ... + } + ``` + + + +## Entity collections + + + + + + 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`. + + + Must be `GET`. + + + Must be either a [Collection](/structures/collection) or a [URICollection](/structures/collection#uri-collection) as JSON. + + + + + + + ```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", + // ... + } + ``` + + + +### 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 +``` diff --git a/app/api/errors/page.mdx b/app/api/errors/page.mdx new file mode 100644 index 0000000..e69de29 diff --git a/app/api/html/page.mdx b/app/api/html/page.mdx new file mode 100644 index 0000000..e69de29 diff --git a/app/api/rate-limits/page.mdx b/app/api/rate-limits/page.mdx new file mode 100644 index 0000000..e69de29 diff --git a/components/Navigation.tsx b/components/Navigation.tsx index 9a53fe1..5ef4a98 100644 --- a/components/Navigation.tsx +++ b/components/Navigation.tsx @@ -270,6 +270,16 @@ export const navigation: NavGroup[] = [ { title: "Example", href: "/federation/example" }, ], }, + { + title: "API", + links: [ + { title: "Basics", href: "/api/basics" }, + { title: "Endpoints", href: "/api/endpoints" }, + { title: "Rate Limits", href: "/api/rate-limits" }, + { title: "Errors", href: "/api/errors" }, + { title: "HTML Redirects", href: "/api/html" }, + ], + }, { title: "Structures", links: [