maas.yml

openapi: 3.0.0
info:
  title: MaaS
  description: MaaS (Matomat as a Service) API definition
  version: 0.5.2
servers:
  - url: https://maas.intern.k4cg.org/v0
    description: The production server
  - url: https://localhost:8443/v0
    description: Local test setup
tags:
- name: auth
  description: Authentication and authorization related operations
- name: users
  description: User management related operations
- name: items
  description: Item related operations
paths:
  /auth/login:
    post:
      tags:
      - auth
      summary: Logs a user in and returns an JWT token for authentication
      description: Logs a user in and returns an JWT token for authentication. The passes along validitiyseconds determine how long the token should be available.
      requestBody:
        description: User information required for login
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
                validityseconds:
                  type: integer
                  format: int32
                  minimum: 0
              required:
                - username
                - password
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthSuccess'
        400:
          description: Invalid username/password supplied
  /items:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: List all available items
      description: Returns a map of item objects, with the item ID as key and the object as value
      responses:
        200:
          description: List of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Add a new item
      description: Adds a new item to matomat. This can only be done by admins
      requestBody:
        description: Information required to create an item
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: The name of the item
                  type: string
                cost:
                  description: The number of credits a single consumption of this Item requires (unit for credits is smallest unit in currency used)
                  type: integer
                  format: int32
                  minimum: 0
              required:
                - name
                - cost
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /items/stats:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Get consumption stats of all items
      description: Get the matomat stats for all items
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ItemStats'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /items/{itemId}:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Get a certain Item
      description: Get a certain Item
      parameters:
      - in: path
        name: itemId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the Item that needs to be fetched
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Update Item
      description: Update Item. This can only be done by admins
      parameters:
      - in: path
        name: itemId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the Item that needs to be updated
      requestBody:
        description: Information required to update an item
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: The name of the item
                  type: string
                cost:
                  description: The number of credits a single consumption of this Item requires (unit for credits is smallest unit in currency used)
                  type: integer
                  format: int32
                  minimum: 0
              required:
                - name
                - cost
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Delete Item
      description: Delete the Item. This can only be done by admins. (Should only mark a Item as deleted to not loose reference for stats)
      parameters:
      - in: path
        name: itemId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the Item that needs to be deleted
      responses:
        200:
          description: Success. Returns the deleted item object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /items/{itemId}/consume:
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Consumes a Item
      description: Consumes a Item and subtracts the cost of the Item from the credit of the user. 
      parameters:
      - in: path
        name: itemId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the Item that needs to be consumed
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemStats'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /items/{itemId}/stats:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - items
      summary: Get consumption stats
      description: Get the matomat stats for a certain Item
      parameters:
      - in: path
        name: itemId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the Item for which to fetch the stats
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemStats'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: List all users
      description: List all users
      responses:
        200:
          description: List of user objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Add a new user
      description: Add a new user. Only admin users are allowed to do this. If "admin" is greater than 0, the new user will be created as admin user.
      requestBody:
        description: Information required to create an user
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: The name of the user
                  type: string
                password:
                  type: string
                passwordrepeat:
                  type: string
                admin:
                  type: integer
              required:
                - name
                - password
                - passwordrepeat
                - admin
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Get user by user ID
      description: Get user by user ID. Returns a user object
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The user ID that needs to be fetched
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Delete user
      description: Delete user. This can only be done by the logged in user (for self) or an admin
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user to be deleted
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/credits/add:
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Add users credits
      description: Add users credits. This can only be done by the logged in user or a admin.
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user for which the credits should be changed
      requestBody:
        description: Credits withdrawl information
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                credits:
                  type: integer
                  format: int32
                  minimum: 0
              required:
                - credits
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/admin/set:
    put:
      security:
        - jwtTokenAuth: []
      tags:
        - users
      summary: Promote a user to admin
      description: Promote a user to admin. This can only be done by other admin users.
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
            format: int32
          required: true
          description: The ID of the user to promote to admin
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        403:
          description: Logged in user is not allowed to promote given user to admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/admin/unset:
    put:
      security:
        - jwtTokenAuth: []
      tags:
        - users
      summary: Remove admin capabilities from an user
      description: Remove admin capabilities from an user. This can only be done by other admin users.
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
            format: int32
          required: true
          description: The ID of the user to remove admin capabilities from
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        403:
          description: Logged in user is not allowed to remove the admin capabilities from the given user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/credits/withdraw:
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Widthdraw users credits
      description: Widthdraw users credits. A user can only withdraw as many credits as she currently has, if more than available are attempted to withdraw, an error is returned and no withdrawl performed. This can only be done by the logged in user or a admin.
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user for which the credits should be changed
      requestBody:
        description: A - not negative - amount of credits
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                credits:
                  type: integer
                  format: int32
                  minimum: 0
              required:
                - credits
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        412:
          description: Not enough credits to withdraw desired amount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/credits/transfer:
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Transfer credits
      description: Transfers credits from logged in user to given user
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user to transfer credits to
      requestBody:
        description: A - not negative - amount of credits to transfer
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                credits:
                  type: integer
                  format: int32
                  minimum: 0
              required:
                - credits
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferredCredits'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/stats:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Get matomat stats for user
      description: Get the matomat stats for user. A user can only request the stats for herself
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user for which to fetch the stats
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStats'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/password:
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Change password for currently logged in user.
      description: Change password for currently logged in user. Must provide old and new passwords (twice) in order to be allowed to change it.
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user for which the password should be changed
      requestBody:
        description: The new password
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                password:
                  type: string
                passwordnew:
                  type: string
                passwordrepeat:
                  type: string
              required:
                - password
                - passwordnew
                - passwordrepeat
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/resetpassword:
    put:
      security:
      - jwtTokenAuth: []
      tags:
      - users
      summary: Set password for user ID
      description: Set password for user ID. This can only be done by a logged in admin for a different user than self.
      parameters:
      - in: path
        name: userId
        schema:
          type: integer
          format: int32
        required: true
        description: The ID of the user for which the password should be changed
      requestBody:
        description: The new password
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                passwordnew:
                  type: string
                passwordrepeat:
                  type: string
              required:
                - passwordnew
                - passwordrepeat
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /service/stats:
    get:
      security:
      - jwtTokenAuth: []
      tags:
      - service
      summary: Total service stats
      description: Total service stats
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStats'
        default:
          description: An error occured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    jwtTokenAuth:            # faking JWT bearer authentication using api key type
      type: apiKey
      in: header
      name: Authorization
  schemas:
    AuthSuccess:
      type: object
      properties:
        token:
          type: string
        expires:
          type: integer
          format: int32
        user:
          $ref: '#/components/schemas/User'
    User:
      type: object
      properties:
        id:
          type: integer
          format: int32
        username:
          type: string
        credits:
          type: integer
          format: int32
        admin:
          type: boolean
    TransferredCredits:
      description: The information on the sending user after the transaction, as well as the amount transferred
      type: object
      properties:
        sender:
          $ref: '#/components/schemas/User'
        credits:
          type: integer
          format: int32
    UserStats:
      description: Consumption stats of a user
      type: array
      items:
        $ref: '#/components/schemas/ItemStats'
    Item:
      description: Represenation of a Item, containing its name and cost (in credits)
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        cost:
          type: integer
          format: int32
    ItemStats:
      description: Stats on a certain item
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        cost:
          type: integer
          format: int32
        consumed:
          type: integer
          format: int32
    ServiceStats:
      description: Stats on the service
      type: object
      properties:
        items:
          type: object
          properties:
            count:
              type: integer
              format: int32
            cost:
              type: object
              properties:
                avg:
                  type: integer
                  format: int32
                min:
                  type: integer
                  format: int32
                max:
                  type: integer
                  format: int32
        users:
          type: object
          properties:
            count:
              type: integer
              format: int32
            credits:
              type: object
              properties:
                sum:
                  type: integer
                  format: int32
                avg:
                  type: integer
                  format: int32
                min:
                  type: integer
                  format: int32
                max:
                  type: integer
                  format: int32
    Error:
      description: Represenation of an error
      type: object
      properties:
        message:
          type: string