kleo-api-v5.yaml

swagger: '2.0'
info:
  version: "5.0.5"
  title: Kleo Classes and Passes Management API
  description: The API provides endpoints for managing users, courses, sessions and passes.

basePath: /api
schemes:
  - http
produces:
  - "application/vnd.tum.aes.kleo.v5.0.5+json"

securityDefinitions:
  OAuth2Password:
    type: oauth2
    flow: password
    tokenUrl: "oauth/token"
    scopes:
      undefined: "Scopes are not used"

tags:
- name: "groups"
- name: "passes"
- name: "users"
- name: "students"
- name: "tutors"

paths:
  /users/:
    get:
      tags:
        - users
      operationId: getUsers
      security:
        - OAuth2Password: []
      responses:
        200:
          description: List of users cached from TUM Shibboleth SSO
          schema:
            type: array
            minItems: 0
            items:
              $ref: '#/definitions/UserDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /users/{userId}:
    get:
      tags:
        - users
      operationId: getUser
      security:
        - OAuth2Password: []
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        200:
          description: A Used object
          schema:
            $ref: '#/definitions/UserDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
    delete:
      tags:
        - users
      operationId: deleteUser
      security:
        - OAuth2Password: []
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        204:
          description: User removed
        404:
          description: Entity not found
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /users/{userId}/roles:
    put:
      tags:
        - users
      operationId: updateUserRoles
      security:
        - OAuth2Password: []
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - in: body
          name: roles
          schema:
            type: array
            minItems: 0
            items:
              type: string
              enum: [SUPERUSER, TUTOR, STUDENT]
      responses:
        200:
          description: User roles has been updated
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /users/{userId}/attendances:
    get:
      tags:
        - users
        - students
        - groups
      operationId: getStudentAttendances
      security:
        - OAuth2Password: []
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        200:
          description: List of attended sessions
          schema:
            type: array
            minItems: 0
            items:
              $ref: '#/definitions/AttendanceDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /users/{userId}/registrations:
    get:
      tags:
        - users
        - students
        - groups
      operationId: getStudentGroups
      security:
        - OAuth2Password: []
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        200:
          description: List of registrations for groups and courses
          schema:
            type: array
            minItems: 0
            items:
              $ref: '#/definitions/GroupDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/:
    get:
      tags:
        - groups
      operationId: getGroups
      security:
        - OAuth2Password: []
      responses:
        200:
          description: A list of Groups
          schema:
            type: array
            minItems: 0
            items:
              $ref: '#/definitions/GroupDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
    post:
      tags:
        - groups
      operationId: addGroup
      security:
        - OAuth2Password: []
      parameters:
      - in: body
        name: group
        schema:
          $ref: '#/definitions/GroupDTO'
      responses:
        201:
          description: A Group created
          schema:
            $ref: '#/definitions/GroupDTO'
        400:
          description: Problem with the request, such as a missing, invalid or type mismatched parameter
          schema:
            $ref: '#/definitions/ErrorDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/:
    get:
      tags:
        - groups
      operationId: getGroup
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
      responses:
        200:
          description: A Group object
          schema:
            $ref: '#/definitions/GroupDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
    patch:
      tags:
        - groups
      operationId: updateGroup
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
        - in: body
          name: group
          schema:
            $ref: '#/definitions/GroupDTO'
      responses:
        200:
          description: A updated Group
          schema:
            $ref: '#/definitions/GroupDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
    delete:
      tags:
        - groups
      operationId: "deleteGroup"
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
      responses:
        204:
          description: The Group has been deleted sucessufly
        404:
          description: Entity not found
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/students:
    get:
      tags:
        - groups
        - students
      operationId: getGroupStudents
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
      responses:
        200:
          description: A list of Students from the given Group
          schema:
            type: array
            minItems: 0
            items:
              $ref: '#/definitions/UserDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/students/{userId}:
    put:
      tags:
        - groups
        - students
      operationId: addGroupStudent
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
        - name: userId
          in: path
          required: true
          type: string
      responses:
        200:
          description: Student has been added to the Group successfully
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
    delete:
      tags:
        - groups
        - students
      operationId: "deleteGroupStudent"
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
        - name: userId
          in: path
          required: true
          type: string
      responses:
        204:
          description: User has been removed from the Group
        404:
          description: Entity not found
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/sessions/:
    post:
      tags:
        - groups
      operationId: addGroupSession
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
        - in: body
          name: session
          schema:
            $ref: '#/definitions/SessionDTO'
      responses:
        201:
          description: A Session created
          schema:
            $ref: '#/definitions/SessionDTO'
        400:
          description: Problem with the request, such as a missing, invalid or type mismatched parameter
          schema:
            $ref: '#/definitions/ErrorDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/sessions/{sessionId}:
    put:
      tags:
        - groups
      operationId: updateGroupSession
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
        - name: sessionId
          in: path
          required: true
          type: string
        - in: body
          name: session
          schema:
            $ref: '#/definitions/SessionDTO'
      responses:
        200:
          description: Session has been updated to the Group successfully
          schema:
            $ref: '#/definitions/SessionDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
    delete:
      tags:
        - groups
      operationId: "deleteGroupSession"
      security:
        - OAuth2Password: []
      parameters:
        - name: groupIdOrCode
          in: path
          required: true
          type: string
        - name: sessionId
          in: path
          required: true
          type: string
      responses:
        204:
          description: Session has been removed from the Group
        404:
          description: Entity not found
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/passes:
    post:
      tags:
        - groups
        - passes
      operationId: generateSessionPass
      security:
        - OAuth2Password: []
      parameters:
      - name: groupIdOrCode
        in: path
        required: true
        type: string
      - in: body
        name: pass
        schema:
          $ref: '#/definitions/PassDTO'
      responses:
        201:
          description: A Pass created
          schema:
            $ref: '#/definitions/PassDTO'
        400:
          description: Problem with the request, such as a missing, invalid or type mismatched parameter
          schema:
            $ref: '#/definitions/ErrorDTO'
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'
  /groups/{groupIdOrCode}/passes/{passCode}:
    put:
      tags:
        - groups
        - passes
      operationId: utilizeSessionPass
      security:
        - OAuth2Password: []
      parameters:
      - name: groupIdOrCode
        in: path
        required: true
        type: string
      - name: passCode
        in: path
        required: true
        type: string
      responses:
        200:
          description: A Pass has been utilized
        500:
          description: Internal server error, please contact support
          schema:
            $ref: '#/definitions/ErrorDTO'

definitions:
  UserDTO:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      email:
        type: string
      studentId:
        type: string
      roles:
        type: array
        items:
          type: string
          enum: [SUPERUSER, TUTOR, STUDENT]
  AttendanceDTO:
    type: object
    properties:
      group:
        $ref: '#/definitions/GroupDTO'
      session:
        $ref: '#/definitions/SessionDTO'
      attendedAt:
        type: string
        format: date-time
      passCode:
        type: string
  GroupDTO:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      code:
        type: string
        readOnly: true
      studentIds:
        type: array
        items:
          type: string
      sessions:
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/SessionDTO'
  SessionDTO:
    type: object
    properties:
      id:
        type: string
      type:
        type: string
        enum: [EXERCISE, TUTORIAL, SEMINAR, OTHER]
      location:
        type: string
      begins:
        type: string
        format: date-time
      ends:
        type: string
        format: date-time
  PassDTO:
    type: object
    properties:
      code:
        type: string
      sessionId:
        type: string
      studentId:
        type: string
      requestedAt:
        type: string
        format: date-time
      expireIn:
        type: integer
        description: in seconds
      expiresAt:
        type: string
        format: date-time
        readOnly: true
  ErrorDTO:
    type: object
    description: Describes a failure occured
    properties:
      timestamp:
        type: string
        format: date
      status:
        type: integer
      error:
        type: string
      exception:
        type: string
        description: A java exception class name
      message:
        type: string
      path:
        type: string