diff --git a/app/api/basics/page.mdx b/app/api/basics/page.mdx index e71fe4b..78e6591 100644 --- a/app/api/basics/page.mdx +++ b/app/api/basics/page.mdx @@ -65,6 +65,7 @@ This is forbidden: ```http GET /.versia/v0.6/entities/user/1234 Host: example.com +Accept: application/vnd.versia+json HTTP/1.1 301 Moved Permanently Location: https://example.com/users/1234 @@ -74,7 +75,8 @@ This is allowed: ```http GET /.versia/v0.6/entities/user/1234 Host: example.com +Accept: text/html HTTP/1.1 301 Moved Permanently -Location: https://example.com/.versia/v0.6/entities/user/1234 +Location: https://example.com/users/1234 ``` \ No newline at end of file diff --git a/app/api/endpoints/page.mdx b/app/api/endpoints/page.mdx index 33f1db0..22d95b1 100644 --- a/app/api/endpoints/page.mdx +++ b/app/api/endpoints/page.mdx @@ -5,6 +5,58 @@ export const metadata = { # Endpoints +## Well-known + + + This endpoint is exempt from the signature requirement. No signatures are required for requests or responses to it. + + The following `Accept` headers are also allowed for requests to this endpoint: + - `application/jrd+json` + - `application/json` + + + + + + + + Must be `/.well-known/versia`. + + + Must be `GET`. + + + A small JSON object with a single attribute: + + - `versions`: Supported Versia Protocol versions. + - Versions marked as "Working Draft X" are represented as `0.X`. + + + + + + + ```http {{ 'title': 'Example request' }} + GET /.well-known/versia + Host: b.social + Accept: application/jrd+json + ``` + + ```http {{ 'title': 'Example response' }} + HTTP/1.1 200 OK + Content-Type: application/jrd+json + + { + "versions": [ + "0.6.0", + "0.5.0" + ] + } + ``` + + + + ## Instance metadata diff --git a/app/api/errors/page.mdx b/app/api/errors/page.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/app/api/html/page.mdx b/app/api/html/page.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/app/api/rate-limits/page.mdx b/app/api/rate-limits/page.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/app/changelog/page.mdx b/app/changelog/page.mdx index 2f5ae46..4147243 100644 --- a/app/changelog/page.mdx +++ b/app/changelog/page.mdx @@ -11,8 +11,10 @@ This page lists changes since Working Draft 3. {{ className: 'lead' }} ## Since WD 5 - Added a new `content-type` for Versia entities: `application/vnd.versia+json`. +- 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. - Removed per-User keypairs: now, only the instance keypair is used for signing. - Moved [Delegation](/extensions/delegation) to an extension +- Changed the contents of the [Well-Known Versia Endpoint](/api/endpoints#well-known) to only list supported protocol versions. - Modified how URIs and references to other entities are handled: - The `uri` field has been removed from all entities. - Every field that used to be a URI now uses that entity's `id` field. diff --git a/app/federation/discovery/page.mdx b/app/federation/discovery/page.mdx index d317b52..fe56937 100644 --- a/app/federation/discovery/page.mdx +++ b/app/federation/discovery/page.mdx @@ -49,11 +49,32 @@ Accept: application/jrd+json ## Instance Discovery -Instance 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. +Instance metadata can be accessed in two steps: + +1. Making a `GET` request to the instance's [`/.well-known/versia` endpoint](/api/endpoints#well-known) to discover supported Versia Protocol versions. +2. Picking a protocol version to use, and then querying the instance metadata endpoint as 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/.versia/v0.6/instance`. +To discover the metadata of the instance `versia.social`, an instance would first make a `GET` request to `https://versia.social/.well-known/versia`. + +```http {{ 'title': 'Example Request' }} +GET /.well-known/versia HTTP/1.1 +Accept: application/json +``` + +```jsonc {{ 'title': 'Example Response' }} +{ + "versions": [ + "0.6.0", + "0.5.0" + ] +} +``` + +Then, we +- Pick version `0.6.0` to use +- Make a `GET` request to `https://versia.social/.versia/v0.6/instance`. This endpoint will return an [InstanceMetadata](/entities/instance-metadata) entity. @@ -72,7 +93,8 @@ Accept: application/vnd.versia+json }, "compatibility": { "versions": [ - "0.5.0" + "0.5.0", + "0.6.0" ], "extensions": [ "pub.versia:reactions", diff --git a/components/Navigation.tsx b/components/Navigation.tsx index a435917..4d088f9 100644 --- a/components/Navigation.tsx +++ b/components/Navigation.tsx @@ -275,9 +275,6 @@ export const navigation: NavGroup[] = [ 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" }, ], }, {