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: List rooms on the server
      parameters:
        filter:
          in: query
          required: true
          description: |
            Must be one of following values:
            - "public": list all public rooms on the server.
            - "joined": list rooms the user have joined.
            - "unseen": list rooms the user have joined and have unseen
              messages.
        top:
          in: query
          description:
            The maximum number of items returned in each page. This is only an
            advice and server can clamp it to a smaller value.
        skipToken:
          in: query
          description:
            The page token returned from a previous list response to fetch the
            next page. NB. Other parameters (eg. `joined` and `page_len`)
            should be included (as the same value) for each page fetch.
      headers:
        Authorization:
          description: |
            Proof of membership for private rooms.
            Required if `filter` is other than "public".
          required: false
          schema:
            $ret: WithSig<AuthPayload>
      responses:
        200:
          content:
            application/json:
              $ref: '#/components/schema/RoomList'
        401:
          description: Missing or invalid Authorization header.
          content:
            application/json:
              $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: Id of the newly created room (rid).
        403:
          description: The user does not have permission to create room.
          content:
            application/json:
              $ref: '#/components/schemas/ApiError'

  /room/{rid}:
    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/{rid}/feed.json:
    get:
      summary: JSON feed of room {rid}, 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/{rid}/item:
    get:
      summary: Get chat history for room {rid}
      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:
        top:
          in: query
          description: |
            The maximum number of items to return. This is an advice and may be
            ignored by server.
        skipToken:
          in: query
          description: |
            Retrieve the next page of items, by providing the last item's `cid`
            from the previous response.
      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 {rid}
      requestBody:
        content:
          application/json:
            schema:
              $ref: WithItemId<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: string
              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/{rid}/item/{cid}/seen:
    post:
      summary: Mark item {cid} in room {rid} seen by the current user.
      description:
        Server will enforce that last seen item does not go backward. Marking
        an older item seen or sending the same request multiple times will be a
        no-op.
      headers:
        Authorization:
          description: Proof of membership for private rooms.
          schema:
            $ret: WithSig<AuthPayload>
      responses:
        204:
          description: Operation completed.
        404:
          description: |
            Room does not exist or the user is not in the room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'

  /room/{rid}/admin:
    post:
      summary: Room management
      requestBody:
        content:
          application/json:
            schema:
              $ref: WithSig<AdminPayload>
              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

    RoomList:
      type: object
      required:
        - rooms
      properties:
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/RoomMetadataForList'
        next_token:
          type: string
          description: An opaque token to fetch the next page.

    RoomMetadataForList:
      type: object
      required: ['rid', 'title', 'attrs']
      properties:
        rid:
          type: string
        title:
          type: string
        attrs:
          type: int64
        last_chat:
          $ref: 'WithItemId<WithSig<ChatPayload>>'
        last_seen_cid:
          type: string

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

    RoomItems:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: 'WithItemId<WithSig<ChatPayload>>'
        skip_token:
          type: string