openapi: 3.0.0
info:
  title: Chat API
  description: API definition for the Chat project
  version: 1.0.0
  license:
    name: GPL-3.0
tags:
  - name: users
  - name: admin
paths:
  /admin/{object}/list:
    get:
      x-draig-di-service: admin.object.list
      operationId: getAdminObjectListExt
      tags:
        - admin
      summary: Get a list of items of any object in the DB using an external class via DI
      parameters:
        - name: object
          in: path
          required: true
          description: Object name of the object in the DB
          schema:
            type: string
            enum:
              - worlds
              - users
              - groups
              - messages
              - channels
      responses:
        '200':
          description: An array of object of the given type
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /users/{name}/avatar:
    get:
      x-draig-di-service: user.avatar
      operationId: getUserAvatarExt
      tags:
        - users
      summary: Get avatar from external source (DI)
      parameters:
        - name: name
          in: path
          required: true
          description: Name to give as a parameter for avatar hash
          schema:
            type: string
      responses:
        '200':
          description: Valid response from the avatar
          content:
            image/png:
              schema:
                type: string
                format: binary
  /users:
    post:
      operationId: postUser
      tags:
        - users
      summary: Create an object of type User
      responses:
        '201':
          description: Object of User type as stored in the DB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: reject invalid data or missing data provided
          x-draig-validation-fixture:
            inbody: '{}'
        '415':
          description: unsupported media type not_provided
          x-draig-validation-fixture:
            inbody: null
      requestBody:
        required: true
        description: Properties of the User object to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
    get:
      operationId: getUser
      tags:
        - users
      summary: Get all (or one) User of current collection
      parameters:
        - name: id
          in: query
          description: Id of the User you want to retrieve
          schema:
            type: integer
        - name: fetch_rels
          in: header
          description: 'Relation fetch specification (see Objection Guide#find-queries). One or more of: world, followed, owned.[members], moderated'
          schema:
            type: array
            items:
              type: string
          explode: true
      x-draig-allow-graph:
        - world
        - followed
        - 'owned.[members]'
        - moderated
      responses:
        '200':
          description: Almost one User is found (or more)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          x-draig-test-fixture:
            id: 1
        '404':
          description: No data was found. Check your criteria for typos
          x-draig-test-fixture:
            id: 9999
  '/users/{id}':
    put:
      operationId: putUser
      tags:
        - users
      summary: Update one or more properties of the stored User object
      parameters:
        - name: id
          required: true
          in: path
          description: Id of the User you want to update
          schema:
            type: integer
      responses:
        '200':
          description: Updated User
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: id is integer
          x-draig-validation-fixture:
            inpath:
              id: '"a"'
            inbody: '{}'
        '404':
          description: No data found
          x-draig-test-fixture:
            id: 9999
            body: '{}'
      requestBody:
        required: true
        description: Selected property/value pairs of the User to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
    patch:
      operationId: patchUser
      tags:
        - users
      summary: Update one or more properties of the stored User object
      parameters:
        - name: id
          required: true
          in: path
          description: Id of the User you want to update
          schema:
            type: integer
      responses:
        '200':
          description: Updated User
        '400':
          description: id is integer
          x-draig-validation-fixture:
            inpath:
              id: '"a"'
            inbody: '{}'
        '404':
          description: No data found
          x-draig-test-fixture:
            id: 9999
            body: '{}'
      requestBody:
        required: true
        description: Selected property/value pairs of the User to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseUser'
components:
  schemas:
    User:
      x-draig-tableName: users
      x-draig-optional: BaseUser
      description: >-
        User resource that will be user only for POST operations (includes DB
        requires)
      required:
        - username
      allOf:
        - $ref: '#/components/schemas/BaseUser'
        - type: object
          properties:
            id:
              type: integer
            followed:
              type: array
              items:
                $ref: '#/components/schemas/Group'
            moderated:
              type: array
              items:
                $ref: '#/components/schemas/Group'
            owned:
              type: array
              items:
                $ref: '#/components/schemas/Group'
              x-draig-sch-recip: owner
            world:
              $ref: '#/components/schemas/World'
    BaseUser:
      description: >-
        User resource that will be user only for PATCH operations.
        Only references to related objects' IDs are needed to allow the
        relate or unrelate graph operations on the object.
      allOf:
        - $ref: '#/components/schemas/Autoincrement'
        - type: object
          properties:
            username:
              type: string
            followed:
              type: array
              items:
                $ref: '#/components/schemas/Autoincrement'
            moderated:
              type: array
              items:
                $ref: '#/components/schemas/Autoincrement'
            owned:
              type: array
              items:
                $ref: '#/components/schemas/Autoincrement'
            world:
              $ref: '#/components/schemas/Autoincrement'
    World:
      x-draig-tableName: worlds
      required:
        - name
      allOf:
        - $ref: '#/components/schemas/Autoincrement'
        - type: object
          properties:
            name:
              type: string
    Group:
      x-draig-tableName: groups
      required:
        - name
        - owner
      allOf:
        - $ref: '#/components/schemas/Autoincrement'
        - type: object
          properties:
            name:
              type: string
            admins:
              x-draig-sch-relation: users_moderated
              type: array
              items:
                $ref: '#/components/schemas/User'
            members:
              x-draig-sch-relation: users_followed
              type: array
              items:
                $ref: '#/components/schemas/User'
            owner:
              $ref: '#/components/schemas/User'
            channels:
              type: array
              items:
                $ref: '#/components/schemas/Channel'
              x-draig-sch-recip: group
    Autoincrement:
      type: object
      properties:
        id:
          x-draig-sch-type-autokey: true
          description: Id generated and returned by the system - send 0 or ignore
          type: integer
    Message:
      description: Messages issued from the users to the channels
      x-draig-tableName: messages
      required:
        - line
      allOf:
        - $ref: '#/components/schemas/Autoincrement'
        - type: object
          properties:
            line:
              type: string
              maxLength: 255
              minLength: 1
    Channel:
      description: Named channels where users can reach others to chat with
      x-draig-tableName: channels
      required:
        - name
        - group
      allOf:
        - $ref: '#/components/schemas/Autoincrement'
        - type: object
          properties:
            name:
              type: string
              maxLength: 32
              minLength: 5
            group:
              $ref: '#/components/schemas/Group'