LogoVersia Protocol Dev

HTTP

Versia uses the HTTP protocol for all communications between instances. HTTP requests must conform to certain standards to ensure compatibility between different implementations, as well as to ensure the security and integrity of the data being exchanged.

HTTP requests/responses between instances must include a Signature, signed with the instance's private key, as defined in Signatures.

Requests

  • Name
    Accept
    Required
    Required
    Type
    string
    Description

    Must be application/vnd.versia+json, unless specified otherwise. Basic application/json is not allowed.

  • Name
    Content-Type
    Required
    Required
    Type
    string
    Description

    Must be application/vnd.versia+json; charset=utf-8 if the request has a body.

  • Name
    Versia-Signature
    Required
    Required
    Type
    string
    Description

    See Signatures for more information.

  • Name
    Versia-Signed-By
    Required
    Required
    Type
    Domain
    Description

    See Signatures.

  • Name
    Versia-Signed-At
    Required
    Required
    Type
    number
    Description

    See Signatures.

  • Name
    User-Agent
    Type
    string
    Description

    A string identifying the software making the request. Should contain the name of the software, its version, and a link to its homepage.

    Example User-Agent

    CoolServer/1.0 (https://coolserver.com)

Example Request

POST https://bob.com/.versia/v0.6/inbox HTTP/1.1
# This specific endpoint returns plain JSON
Accept: application/json
User-Agent: CoolServer/1.0 (https://coolserver.com)
Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==
Versia-Signed-By: example.com
Versia-Signed-At: 1729241687

Rate limits

Implementations must respect the rate limits of remote instances.

IETF draft draft-polli-ratelimit-headers-02 must be used to communicate rate limits. Other rate limit headers/formats are not allowed.

This IETF draft is, well, a draft. However, there are no standards for rate limiting in HTTP, so this is the best we have.

Responses

  • Name
    Content-Type
    Required
    Required
    Type
    string
    Description

    Must include application/vnd.versia+json; charset=utf-8, unless specified otherwise.

  • Name
    Versia-Signature
    Required
    Required
    Type
    string
    Description

    See Signatures for more information.

  • Name
    Versia-Signed-By
    Required
    Required
    Type
    Domain
    Description

    See Signatures.

  • Name
    Versia-Signed-At
    Required
    Required
    Type
    number
    Description

    See Signatures.

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.versia+json; charset=utf-8
Versia-Signature: /CjB2L9bcvRg+uP19B4/rqy7Ji9/cqMFPlL3GVCIndnQjYyOpBzJEAl9weDnXm7Jrqa3y6sBC+EYWKThO2r9Bw==+7BvnWKITyGyTwHbb6fVYwRx1I
Versia-Signed-By: example.com
Versia-Signed-At: 1729241717