mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
feat: ✨ Document basics of S2S Federation API, and some endpoints
Some checks failed
Mirror to Codeberg / Mirror (push) Failing after 0s
Some checks failed
Mirror to Codeberg / Mirror (push) Failing after 0s
This commit is contained in:
Jesse Wierzbinski
parent
3f94eff3e3
commit
71064dea2c
27
app/api/basics/page.mdx
Normal file
27
app/api/basics/page.mdx
Normal file
|
|
@ -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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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).
|
||||
150
app/api/endpoints/page.mdx
Normal file
150
app/api/endpoints/page.mdx
Normal file
|
|
@ -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
|
||||
```
|
||||
0
app/api/errors/page.mdx
Normal file
0
app/api/errors/page.mdx
Normal file
0
app/api/html/page.mdx
Normal file
0
app/api/html/page.mdx
Normal file
0
app/api/rate-limits/page.mdx
Normal file
0
app/api/rate-limits/page.mdx
Normal file
|
|
@ -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: [
|
||||
|
|
|
|||
Loading…
Reference in a new issue