api.yml

openapi: 3.0.0
servers:
  - description: default
    url: https://bbs.hedlx.org/api
  - description: local
    url: http://127.0.0.1:8001
info:
  description: Shallow BBS API definition
  version: "0.1"
  title: hedλx BBS API

paths:
  /threads:
    get:
      summary: Get threads ordered by bumpness.
      operationId: getThreads
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
            minimum: 0
          description: Default is 100.
        - in: query
          name: offset
          schema:
            type: integer
            format: int32
            minimum: 0
          description: ""
      responses:
        200:
          description: Object containing latest threads and some meta info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Threads'
        400: { description: Bad input parameter. }
    post:
      summary: Create new thread.
      operationId: createThread
      responses:
        200: { description: Tthread created }
        400: { description: Invalid input. }
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewThread'
  /threads/{id}:
    parameters:
      - name: id
        in: path
        description: Thread id
        required: true
        schema: { type: integer, format: int64, minimum: 1 }
    get:
      summary: Get thread.
      operationId: getThread
      responses:
        200:
          description: array of message objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadFull'
        400:
          description: bad input parameter
    post:
      summary: Post reply to the thread.
      operationId: answerThread
      responses:
        200: { description: Message created. }
        400: { description: Invalid input. }
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessage'
    delete:
      summary: Delete thread.
      responses:
        200: { description: Deleted. }
        401: { description: Invalid password. }
        404: { description: No such thread. }
  /threads/{id}/replies/{no}:
    parameters:
      - name: id
        in: path
        description: Thread id.
        required: true
        schema: { type: integer, format: int64, minimum: 1 }
      - name: no
        in: path
        description: Message number. OP can not be deleted.
        required: true
        schema: { type: integer, format: int64, minimum: 1 }
    delete:
      summary: Delete reply.
      parameters:
        - in: query
          name: password
          description: Password used to post the reply.
          required: true
          schema: { type: string }
      responses:
        200: { description: Deleted. }
        401: { description: Invalid password. }
        404: { description: No such thread or post. }
  /upload:
    post:
      summary: Upload media.
      responses:
        200:
          description: Done.
          content:
            application/json:
              schema:
                type: object
                required: [id]
                properties:
                  id:
                    type: string
                    example: SaVFRRIgvXJfu23KXPG7aTy4KebFuFTUG1mEFSFGwDY

components:
  schemas:
    Threads:
      type: object
      properties:
        count:
          type: integer
          example: 90
          description: Total number of threads.
        threads:
          type: array
          items:
            $ref: '#/components/schemas/ThreadPreview'
    ThreadPreview:
      type: object
      properties:
        id:
          type: integer
          example: 3
        op:
          $ref: '#/components/schemas/Message'
        last:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    ThreadFull:
      type: object
      properties:
        subject:
          type: string
          example: Selling my refrigerator
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    NewMessage:
      type: object
      properties:
        name:
          type: string
          example: Anonymous
        secret:
          type: string
          example: mytripcode
          description: Used to generate tripcode.
        password:
          type: string
          example: mypassword
          description: Password to delete this message.
        text:
          type: string
          example: Incredibly long post text.
        media:
          type: array
          items:
            type: object
            required: [id, type]
            properties:
              id:
                type: string
                example: SaVFRRIgvXJfu23KXPG7aTy4KebFuFTUG1mEFSFGwDY
              orig_name:
                type: string
                example: blabla.jpg
    NewThread:
      type: object
      properties:
        subject:
          type: string
          example: Selling my refrigerator
          description: Subject of a thread.
        password:
          description: Password to delete this thread.
      allOf:
        - $ref: '#/components/schemas/NewMessage'
    Message:
      type: object
      required:
        - no
        - text
        - ts
        - media
      properties:
        no:
          type: integer
          example: 0
          description: Message number within thread. 0 is OP.
        name:
          type: string
          example: Anonymous
        trip:
          type: string
          example: n4Z4Jfg2UgAg
        text:
          type: string
          example: Incredibly long post text.
        ts:
          type: integer
          example: 1136239445
          description: Timestamp.
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
    Media:
      type: object
      required: [id, type, size, width, height, orig_name]
      properties:
        id:
          type: string
          example: SaVFRRIgvXJfu23KXPG7aTy4KebFuFTUG1mEFSFGwDY
        type:
          type: string
          example: image/jpeg
        size:
          type: integer
          example: 28324
        width:
          type: integer
          example: 1024
        height:
          type: integer
          example: 512
        orig_name:
          type: string
          example: blabla.jpg
  parameters:
    id:
      in: query
      name: id
      description: Thread id
      schema:
        type: integer
        format: int64