export const metadata = {
    title: 'HTTP',
    description:
        'How Lysand uses the HTTP protocol for all communications between instances.',
}

# HTTP

Lysand 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.

ALL kinds of HTTP requests/responses between instances **MUST** include a [Signature](/signatures), signed with either the relevant [User](/entities/users)'s private key or the [Server Actor](/entities/server-actor)'s private key.

## Requests

<Row>
    <Col>
        <Properties>
            <Property name="Accept" type="string" required={true}>
                Must include `application/json`.
            </Property>
            <Property name="Content-Type" type="string" required={true}>
                Must include `application/json; charset=utf-8`, if the request has a body.
            </Property>
            <Property name="Signature" type="string" required={false} typeLink="/signatures">
                Request signature, if the request is signed.
            </Property>
            <Property name="Date" type="UTC Time" required={true} typeLink="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Date">
                Date and time of the request.
            </Property>
            <Property name="User-Agent" type="string" required={false}>
                A string identifying the software making the request.
            </Property>
        </Properties>
    </Col>
    <Col sticky>
        ```http {{ 'title': 'Example Request' }}
        POST /users/1/inbox HTTP/1.1
        Accept: application/json
        Signature: keyId="https://example.com/users/1",algorithm="ed25519",headers="(request-target) host date digest",signature="..."
        Date: Thu, 01 Jan 1970 00:00:00 GMT
        User-Agent: CoolServer/1.0 (https://coolserver.com)
        ```
    </Col>
</Row>

## Responses

<Row>
    <Col>
        <Properties>
            <Property name="Content-Type" type="string" required={true}>
                Must include `application/json; charset=utf-8`.
            </Property>
            <Property name="Signature" type="string" required={false} typeLink="/signatures">
                Response signature, if the response is signed.
            </Property>
            <Property name="Date" type="UTC Time" required={true} typeLink="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Date">
                Date and time of the response.
            </Property>
        </Properties>
    </Col>
    <Col sticky>
        ```http {{ 'title': 'Example Response' }}
        HTTP/1.1 200 OK
        Content-Type: application/json; charset=utf-8
        Date: Thu, 01 Jan 1970 00:00:00 GMT
        Signature: keyId="https://example.com/users/1",algorithm="ed25519",headers="(request-target) host date digest",signature="..."
        ```
    </Col>
</Row>