versia-pub/docs
2
0
Fork 0
mirror of https://github.com/versia-pub/docs.git synced 2026-03-13 02:49:16 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: ♻️ Rewrite various docs pages, add null fields everywhere they were missing, make some Note and User fields mandatory

Browse source
This commit is contained in:
Jesse Wierzbinski 2025-06-07 22:54:59 +02:00
parent e6f7a27d3e
commit e9b5ccd76c
No known key found for this signature in database
31 changed files with 412 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

33
app/api/basics/page.mdx
View file

@ -11,23 +11,44 @@ Versia defines a very simple API for server-to-server communication, mainly fetc
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.
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.
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.
<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.
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.
</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.
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).
## 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).
## Domain
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).
Defining a domain is very complicated, so please refer to the following examples:
``` {{ "title": "Valid Domains" }}
example.com
test.localhost
sus.example.org
xn--ls8h.la
1.0.1.7.0.8.0.0.0.0.7.4.0.1.0.0.2.ip6.arpa # We know what you did
```
``` {{ "title": "Invalid Domains" }}
example.com:3000 # ❌️ Invalid: port number is not allowed
test..localhost # ❌️ Invalid: double dot is not allowed
example.com. # ❌️ Invalid: trailing dot is not allowed
test.org/ # ❌️ Invalid: trailing slash is not allowed
test.org/sus # ❌️ Invalid: path is not allowed
💩.la # ❌️ Invalid: IDNs must be Punycode encoded
https://bob.org # ❌️ Invalid: protocol is not allowed
```
## Redirects
API endpoints **MUST NOT** redirect to other endpoints, with the following exceptions:

8
app/api/endpoints/page.mdx
View file

@ -22,7 +22,7 @@ export const metadata = {
Must be `GET`.
</Property>
<Property name="response">
Must be the instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document.
Instance's metadata, as defined in the [Instance Metadata](/entities/instance-metadata) document.
</Property>
</Properties>
@ -66,7 +66,7 @@ export const metadata = {
Must be `GET`.
</Property>
<Property name="response">
Must be the entity's data as JSON, as defined in its [Entity](/entities) definition document.
Entity data as JSON, as defined in its [Entity](/entities) definition document.
</Property>
</Properties>
</Col>
@ -151,9 +151,9 @@ Accept: application/vnd.versia+json
## Inbox
The inbox endpoint is used for other instances to send entities to this instance. It is a single endpoint that can receive messages for every user (also known as a shared inbox).
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).
The delivery mechanism is described further in the [Federation](/federation) document.
The delivery mechanism is described further in the [Federation](/federation#inboxes) document.
<Row>
<Col>