openapi: 3.1.0
info:
  title: Allowance Planner
  version: 1.0.0
servers:
  - url: 'https://allowance_planner.seeseepuff.be/v1'
    description: 'API server'
  - url: 'http://localhost/v1'
    description: 'Local server'
paths:

  /users:
    get:
      summary: Gets all users
      responses:
        200:
          description: Information about every user
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: The user ID
                    name:
                      type: string
                      description: The user name

  /user/{userId}:
    get:
      summary: Gets information about a user
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Information about the user
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The user ID
                  name:
                    type: string
                    description: The user name
                  allowance:
                    type: integer
                    description: The total amount of allowance the user has
        404:
          description: The users could not be found.

  /user/{userId}/allowance:
    post:
      summary: Updates the allowance of a user
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: The amount to update the allowance by, in cents.
                description:
                  type: string
                  description: The description of the allowance or expense.
      responses:
        200:
          description: The allowance was updated successfully.
        400:
          description: The allowance could not be updated.

  /user/{userId}/history:
    get:
      summary: Gets the allowance history of a user
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Information about the allowance history of the user
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date-time
                      description: The date of the allowance or expense.
                    amount:
                      type: integer
                      description: The amount of the allowance to be added, in cents. A negative value

  /user/{userId}/goals:
    get:
      summary: Gets all goals
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Information about the goals of the user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/goal"
    post:
      summary: Creates a new goal
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The goal name. The goal with the name "null" is a special goal that represents the basic allowance functionality.
                target:
                  type: integer
                  description: The target value of the goal, in cents
                weight:
                  type: integer
                  description: How much money goes to this goal, relative to all other goals.
      responses:
        201:
          description: The goal was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The goal ID
        400:
          description: The goal could not be created.
    put:
      summary: Bulk updating of goals
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    description: The goal ID
                  weight:
                    type: integer
                    description: How much money goes to this goal, relative to all other goals.
      responses:
        200:
          description: The goals were updated successfully.
        404:
          description: The goals could not be found.

  /user/{userId}/goal/{goalId}:
    get:
      summary: Gets information about a goal
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
        - in: path
          name: goalId
          description: The goal ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Information about the goal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/goal"
        404:
          description: The goal could not be found.
    put:
      summary: Updates a goal
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
        - in: path
          name: goalId
          description: The goal ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new name of the goal, if set.
                target:
                  type: integer
                  description: The target value of the goal, in cents, if set.
                weight:
                  type: integer
                  description: How much money goes to this goal, relative to all other goals, if set.
      responses:
        200:
          description: The goal was updated successfully.
        404:
          description: The goal could not be found.

    delete:
      summary: Deletes a goal
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
        - in: path
          name: goalId
          description: The goal ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: The goal was deleted successfully.
        404:
          description: The goal could not be found.

  /user/{userId}/goal/{goalId}/complete:
    post:
      summary: Completes a goal.
      description: Completes a goal. This will subtract this goal's value from the user's allowance and then remove the goal.
      parameters:
        - in: path
          name: userId
          description: The user ID
          required: true
          schema:
            type: integer
        - in: path
          name: goalId
          description: The goal ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: The goal was completed successfully.
        404:
          description: The goal could not be found.

  /tasks:
    get:
      summary: Gets all tasks
      responses:
        200:
          description: Information about every task
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/task"
    post:
      summary: Create a new task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The task name
                reward:
                  type: integer
                  description: The task reward, in cents
                assigned:
                  type: integer
                  description: The user ID of the user assigned to the task
      responses:
        202:
          description: The task was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The task ID

  /task/{id}:
    get:
      summary: Gets information about a task
      parameters:
        - in: path
          name: id
          description: The task ID
          required: true
          schema:
            type: integer
        - in: query
          name: sort
          description: The sort order of the tasks
          required: false
          schema:
            type: enum
            enum:
              - reward
              - recent
              - old
      responses:
        200:
          description: Information about the task
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/task"
        404:
          description: The tasks could not be found.
    put:
      summary: Updates a task
      parameters:
        - in: path
          name: id
          description: The task ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The task name
                reward:
                  type: integer
                  description: The task reward, in cents
                assigned:
                  type: integer
                  description: The user ID of the user assigned to the task
      responses:
        200:
          description: The task was updated successfully.
        404:
          description: The task could not be found.

components:
  schemas:
    task:
      type: object
      properties:
        id:
          type: integer
          description: The task ID
        name:
          type: string
          description: The task name
        reward:
          type: integer
          description: The task reward, in cents
        assigned:
          type: integer
          description: The user ID of the user assigned to the task

    goal:
      type: object
      properties:
        id:
          type: integer
          description: The goal ID
        name:
          type: string
          description: The goal name. The goal with the name "null" is a special goal that represents the basic allowance functionality.
        target:
          type: integer
          description: The target value of the goal, in cents
        progress:
          type: integer
          description: The progress of the goal, in cents
        weight:
          type: integer
          description: How much money goes to this goal, relative to all other goals.