blahrs/blahd/docs/webapi.yaml

openapi: 3.1.0
info:
  title: Blah Chatserver Proto
  version: 0.0.1

paths:
  /ws:
    get:
      summary: WebSocket endpoint.
      description: |
        Once connection, client must send a JSON text message of type
        `WithSig<AuthPayload>` for authentication.
        If server does not close it immediately, it means success.

        Then server will send JSON text messages on events that user are
        interested in (eg. chat from joined rooms).
        The message has type `Outgoing` in `blahd/src/ws.rs`.

  /room:
    get:
      summary: Get room metadata
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomMetadata'
        404:
          description: |
            Room does not exist or the user does not have permission to get metadata of it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /room/create:
    post:
      summary: Create a new room
      requestBody:
        content:
          application/json:
            schema:
              $ref: WithSig<CreateRoomPayload>
              example:
                sig: 99a77e836538268839ed3419c649eefb043cb51d448f641cc2a1c523811aab4aacd09f92e7c0688ffd659bfc6acb764fea79979a491e132bf6a56dd23adc1d09
                signee:
                  nonce: 670593955
                  payload:
                    typ: create_room
                    attrs: 1 # PUBLIC_READABLE
                    title: 'hello room'
                    members:
                      - user: 83ce46ced47ec0391c64846cbb6c507250ead4985b6a044d68751edc46015dd7
                        permission: -1
                  timestamp: 1724966284
                  user: 83ce46ced47ec0391c64846cbb6c507250ead4985b6a044d68751edc46015dd7
      responses:
        200:
          content:
            application/json:
              type: string
              description: UUID of the newly created room (ruuid).
        403:
          description: The user does not have permission to create room.
          content:
            application/json:
              $ref: '#/components/schemas/ApiError'

  /room/{ruuid}/feed.json:
    get:
      summary: JSON feed of room {ruuid}, which must be public readable
      description: For human and feed reader consumption only.
      responses:
        200:
          text/feed+json:
            scheme:
              $ref: 'https://www.jsonfeed.org/version/1.1/'
        404:
          description: Room does not exist or is private.
          content:
            application/json:
              $ref: '#/components/schemas/ApiError'

  /room/{ruuid}/item:
    get:
      summary: Get chat history for room {ruuid}
      description: |
        Return chat items in reversed time order, up to PAGE_LEN items.
        The last (oldest) chat id can be used as query parameter for the next
        GET, to repeatedly fetch full history.
      headers:
        Authorization:
          description: Proof of membership for private rooms.
          required: false
          schema:
            $ret: WithSig<AuthPayload>
      parameters:
        before_id:
          description: Filter items before (not including) a given chat id (cid).
          in: query
      responses:
        200:
          content:
            application/json:
              x-description: TODO
        404:
          description: |
            Room does not exist or the user does not have permission to read it.
          content:
            application/json:
              $ref: '#/components/schemas/ApiError'

    post:
      summary: Post a chat in room {ruuid}
      requestBody:
        content:
          application/json:
            schema:
              $ref: WithSig<ChatPayload>
              example:
                sig: 99a77e836538268839ed3419c649eefb043cb51d448f641cc2a1c523811aab4aacd09f92e7c0688ffd659bfc6acb764fea79979a491e132bf6a56dd23adc1d09
                signee:
                  nonce: 670593955
                  payload:
                    typ: chat
                    room: 7ed9e067-ec37-4054-9fc2-b1bd890929bd
                    rich_text: ["before ",["bold ",{"b":true}],["italic bold ",{"b":true,"i":true}],"end"]
                  timestamp: 1724966284
                  user: 83ce46ced47ec0391c64846cbb6c507250ead4985b6a044d68751edc46015dd7
      responses:
        200:
          content:
            application/json:
              type: integer
              description: Created chat id (cid).
        400:
          description: Body is invalid or fails the verification.
          content:
            application/json:
              $ref: '#/components/schemas/ApiError'
        403:
          description: |
            The user does not have permission to post in this room, or the room does not exist.
          content:
            application/json:
              $ref: '#/components/schemas/ApiError'

  /room/{ruuid}/admin:
    post:
      summary: Room management
      requestBody:
        content:
          application/json:
            schema:
              $ref: WithSig<ChatPayload>
              example:
                sig: 99a77e836538268839ed3419c649eefb043cb51d448f641cc2a1c523811aab4aacd09f92e7c0688ffd659bfc6acb764fea79979a491e132bf6a56dd23adc1d09
                signee:
                  nonce: 670593955
                  payload:
                    permission: 1
                    room: 7ed9e067-ec37-4054-9fc2-b1bd890929bd
                    typ: add_member
                    user: 83ce46ced47ec0391c64846cbb6c507250ead4985b6a044d68751edc46015dd7
                  timestamp: 1724966284
                  user: 83ce46ced47ec0391c64846cbb6c507250ead4985b6a044d68751edc46015dd7
      responses:
        204:
          description: Operation completed.
        404:
          description: |
            Room does not exist or the user does not have permission for management.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

components:
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

    RoomMetadata:
      type: object
      properties:
        title:
          type: string
        attrs:
          type: int64