exam-management.yaml

openapi: "3.0.0"
info:
  description: "This is the Exam API for UC4."
  version: "0.17.1"
  title: "UC4"

servers:
  - url: https://uc4.cs.upb.de/api/experimental/exam-management
  - url: https://uc4.cs.upb.de/api/develop/exam-management
  - url: https://uc4.cs.upb.de/api/production/exam-management

tags:
- name: "Version Management"
  description: "Everything about the Version"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"
- name: "Exam Management"
  description: "Everything about the exams"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"

paths:
  /version:
    get:
      tags:
      - "Version Management"
      summary: "Get version"
      description: "Returns the version of the current service"
      operationId: "getVersion"

      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonServiceVersion'
  /version/hyperledger:
    get:
      tags:
      - "Version Management"
      summary: "Get Hyperledger version"
      description: "Returns the version of the current hyperledger backend"
      operationId: "getVersionHyperledger"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonHyperledgerVersion'
  /exams:
    get:
      tags:
      - "Exam Management"
      summary: "Get All Exams"
      description: "When invoked by an Admin and without query parameters, returns all exams. When invoked with query parameters, returns exams filtered by the parameters."
      operationId: "getAllExams"
      parameters:
      - name: "examIds"
        in: "query"
        description: "Comma separated list of ExamIds to filter by"
        required: false
        schema:
          type: "string"
      - name: "courseIds"
        in: "query"
        description: "Comma separated list of CourseIds to filter by"
        required: false
        schema:
          type: "string"
      - name: "lecturerIds"
        in: "query"
        description: "Comma separated list of enrollmentIds of lecturers to filter by"
        required: false
        schema:
          type: "string"
      - name: "moduleIds"
        in: "query"
        description: "Comma separated list of ModuleIds to filter by"
        required: false
        schema:
          type: "string"
      - name: "types"
        in: "query"
        description: "Comma separated list of Types to filter by"
        required: false
        schema:
          type: "string"    
      - name: "admittableAt"
        in: "query"
        description: "Only return exams for which admittableAt is before AdmittableUntil. Date in ISO 8601"
        required: false
        schema:
          type: "string"
      - name: "droppableAt"
        in: "query"
        description: "Only return exams for which droppableAt is before DroppableUntil. Date in ISO 8601"
        required: false
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/Exam'
              examples:
                GetExam:
                  $ref: '#/components/examples/ExampleExamGet'
        "400":
          description: | 
            Bad Request  
            types: MalformedLoginToken, MultipleAuthorizationError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: |
            Unauthorized  
            types: JwtAuthorization, LoginTokenExpired
          content:
            application/json:  
              schema:
                $ref: '#/components/schemas/GenericError'
        "403":
          description: |
            Forbidden  
            types: NotEnoughPrivileges, OwnerMismatch
          content:
            application/json:  
              schema:
                $ref: '#/components/schemas/GenericError'
        "422":
          description: |
            Unprocessable Entity  
            types: LoginTokenSignatureInvalid
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/GenericError'
  /exams/unsigned_add_proposal:
    post:
      tags:
      - "Exam Management"
      summary: "Fetch a proposal for creating an exam"
      description: "Fetch a proposal for creating the exam given in the body."
      operationId: "getProposalAddExam"
      security:
        - uc4_token_login: []
        - uc4_token_login_header: []
      requestBody:
        description: "Exam object based on which an operation is initiated"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Exam'
            examples:
              AddCourseAdmission:
                $ref: '#/components/examples/ExampleExam'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsignedProposal'
              examples:
                ExampleUnsignedProposal:
                  $ref: '#/components/examples/ExampleUnsignedProposal'
        "400":
          description: | 
            Bad Request  
            types: MalformedLoginToken, Deserialization, JsonValidation, MultipleAuthorizationError
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GenericError'
                  - $ref: '#/components/schemas/DetailedError'
        "401":
          description: |
            Unauthorized  
            types: JwtAuthorization, LoginTokenExpired
          content:
            application/json:  
              schema:
                $ref: '#/components/schemas/GenericError'
        "403":
          description: |
            Forbidden  
            types: NotEnoughPrivileges, OwnerMismatch
          content:
            application/json:  
              schema:
                $ref: '#/components/schemas/GenericError'
        "422":
          description: |
            Unprocessable Entity  
            types: Validation, ValidationTimeout, LoginTokenSignatureInvalid
          content:
            application/json: 
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GenericError'
                  - $ref: '#/components/schemas/DetailedError'
  
components:
  securitySchemes:
    uc4_token_login:
      type: apiKey
      in: cookie
      name: login
    uc4_token_login_header:
      type: http
      scheme: bearer
  schemas:
    Exam:
      type: object
      properties:
        examId:
          type: string
        courseId:
          type: string
        moduleId:
          type: string
        lecturerEnrollmentId:
          type: string
        type:
          type: string
          enum: ["Written Exam"]
        date:
          type: string
          format: date
          description: "ISO 8601"
        ects:
          type: integer
        admittableUntil:
          type: string
          format: date
          description: "ISO 8601"
        droppableUntil:
          type: string
          format: date
          description: "ISO 8601"
        
    UnsignedProposal:
      allOf:
        - $ref: 'https://raw.githubusercontent.com/upb-uc4/api/develop/hyperledger-proposals.yaml#/components/schemas/UnsignedProposal'
        - type: object
    JsonServiceVersion:
      type: object
      properties:
        serviceVersion:
          type: string
    JsonHyperledgerVersion:
      type: object
      properties:
        hlfApiVersion:
          type: string
        chaincodeVersion:
          type: string
    GenericError:
      allOf:
        - $ref: 'https://raw.githubusercontent.com/upb-uc4/api/develop/errors.yaml#/components/schemas/GenericError'
        - type: object
    DetailedError:
      allOf:
        - $ref: 'https://raw.githubusercontent.com/upb-uc4/api/develop/errors.yaml#/components/schemas/DetailedError'
        - type: object
  examples:
    ExampleExam:
      summary: "An example for an exam"
      value:
        examId: "eae27105-2fd5-11eb-ad58-572c5dfe1b7a:M.1275.01158:Written Exam:2021-04-01"
        courseId: "eae27105-2fd5-11eb-ad58-572c5dfe1b7a"
        moduleId: "M.1275.01158"
        lecturerEnrollmentId: "e53143d725255d70945989901ebc137a7d35c2b61ffdfecb9a135c6136eea4a6"
        type: "Written Exam"
        date: "2021-04-01"
        ects: 8
        admittableUntil:  "2021-03-01"
        droppableUntil:  "2021-03-25"
    ExampleExamGet:
      summary: "An example for an exam get operation"
      value:
        - examId: "eae27105-2fd5-11eb-ad58-572c5dfe1b7a:M.1275.01158:Written Exam:2021-04-01"
          courseId: "eae27105-2fd5-11eb-ad58-572c5dfe1b7a"
          moduleId: "M.1275.01158"
          lecturerEnrollmentId: "e53143d725255d70945989901ebc137a7d35c2b61ffdfecb9a135c6136eea4a6"
          type: "Written Exam"
          date: "2021-04-01"
          ects: 8
          admittableUntil:  "2021-03-01"
          droppableUntil:  "2021-03-25"
    ExampleUnsignedProposal:
      summary: "Example for UnsignedProposal"
      value:
        unsignedProposal: "CpUJCmoIAxABGgsIgL22/AUQ+NbCWSIJbXljaGFubmVsKkBhMzUwNzA1YWNiMGVmNDUyMzQxN2RjYTRkMTA0ZDUxNmYzMmMxNTgwNzhiYTA4Yzk0NmU1OGRkZWIzZWJhYTJmOgoSCBIGdWM0LWNjEqYICokICgdvcmcxTVNQEv0HLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN4akNDQW0yZ0F3SUJBZ0lVYkFLNmdwb1BGaTQxeEloY1Z5YkdXZUV0cXpBd0NnWUlLb1pJemowRUF3SXcKWURFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVJFd0R3WURWUVFERXdoeVkyRXRiM0puCk1UQWVGdzB5TURFd01Ua3hNelU0TURCYUZ3MHlNVEV3TVRreE5EQXpNREJhTURneERqQU1CZ05WQkFzVEJXRmsKYldsdU1TWXdKQVlEVlFRREV4MXpZMkZzWVMxeVpXZHBjM1J5WVhScGIyNHRZV1J0YVc0dGIzSm5NVEJaTUJNRwpCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQktab1BNRVpYa1VUdHV3R3VZYmE3UWJHcWpxSFRuVnEyeGVDCklERG1kYmMyUkhBMjBEZjMwY3VUN1dHMVJzdGIyWmpoRS9ESWhVQjRlUzMwbkxTRFJobWpnZ0VyTUlJQkp6QU8KQmdOVkhROEJBZjhFQkFNQ0E2Z3dIUVlEVlIwbEJCWXdGQVlJS3dZQkJRVUhBd0VHQ0NzR0FRVUZCd01DTUF3RwpBMVVkRXdFQi93UUNNQUF3SFFZRFZSME9CQllFRk5pbndnNkRveXliS09veEUweENkT2VkOTUraE1COEdBMVVkCkl3UVlNQmFBRkhFN1lISTJwVFhRaWZ4R3o5c2l2cURYTGV1Yk1DZ0dBMVVkRVFRaE1CK0NIWE5qWVd4aExYSmwKWjJsemRISmhkR2x2YmkxaFpHMXBiaTF2Y21jeE1INEdDQ29EQkFVR0J3Z0JCSEo3SW1GMGRISnpJanA3SW1GawpiV2x1SWpvaWRISjFaU0lzSW1obUxrRm1abWxzYVdGMGFXOXVJam9pSWl3aWFHWXVSVzV5YjJ4c2JXVnVkRWxFCklqb2ljMk5oYkdFdGNtVm5hWE4wY21GMGFXOXVMV0ZrYldsdUxXOXlaekVpTENKb1ppNVVlWEJsSWpvaVlXUnQKYVc0aWZYMHdDZ1lJS29aSXpqMEVBd0lEUndBd1JBSWdZdUR6d0I2dU00RnhUTHdWVlRpeGcvWUFTS1U0a0RDQQorN0p2amFHd25RUUNJRUJKTVpUUnc5WmdhVjNpS084S2t6WEw5TGdnUkpIam5pSFVOdWpZME1WVAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tChIYTH47gBwXl+errTr7n7m2byTjHtQteNtsEssICsgICsUICAESCBIGdWM0LWNjGrYICh5VQzQuQ2VydGlmaWNhdGU6YWRkQ2VydGlmaWNhdGUKAzEwMQqOCC0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLVxuTUlJQ3hqQ0NBbTJnQXdJQkFnSVViQUs2Z3BvUEZpNDF4SWhjVnliR1dlRXRxekF3Q2dZSUtvWkl6ajBFQXdJd1xuWURFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ1lEVlFRS1xuRXd0SWVYQmxjbXhsWkdkbGNqRVBNQTBHQTFVRUN4TUdSbUZpY21sak1SRXdEd1lEVlFRREV3aHlZMkV0YjNKblxuTVRBZUZ3MHlNREV3TVRreE16VTRNREJhRncweU1URXdNVGt4TkRBek1EQmFNRGd4RGpBTUJnTlZCQXNUQldGa1xuYldsdU1TWXdKQVlEVlFRREV4MXpZMkZzWVMxeVpXZHBjM1J5WVhScGIyNHRZV1J0YVc0dGIzSm5NVEJaTUJNR1xuQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJLWm9QTUVaWGtVVHR1d0d1WWJhN1FiR3FqcUhUblZxMnhlQ1xuSUREbWRiYzJSSEEyMERmMzBjdVQ3V0cxUnN0YjJaamhFL0RJaFVCNGVTMzBuTFNEUmhtamdnRXJNSUlCSnpBT1xuQmdOVkhROEJBZjhFQkFNQ0E2Z3dIUVlEVlIwbEJCWXdGQVlJS3dZQkJRVUhBd0VHQ0NzR0FRVUZCd01DTUF3R1xuQTFVZEV3RUIvd1FDTUFBd0hRWURWUjBPQkJZRUZOaW53ZzZEb3l5YktPb3hFMHhDZE9lZDk1K2hNQjhHQTFVZFxuSXdRWU1CYUFGSEU3WUhJMnBUWFFpZnhHejlzaXZxRFhMZXViTUNnR0ExVWRFUVFoTUIrQ0hYTmpZV3hoTFhKbFxuWjJsemRISmhkR2x2YmkxaFpHMXBiaTF2Y21jeE1INEdDQ29EQkFVR0J3Z0JCSEo3SW1GMGRISnpJanA3SW1Ga1xuYldsdUlqb2lkSEoxWlNJc0ltaG1Ma0ZtWm1sc2FXRjBhVzl1SWpvaUlpd2lhR1l1Ulc1eWIyeHNiV1Z1ZEVsRVxuSWpvaWMyTmhiR0V0Y21WbmFYTjBjbUYwYVc5dUxXRmtiV2x1TFc5eVp6RWlMQ0pvWmk1VWVYQmxJam9pWVdSdFxuYVc0aWZYMHdDZ1lJS29aSXpqMEVBd0lEUndBd1JBSWdZdUR6d0I2dU00RnhUTHdWVlRpeGcvWUFTS1U0a0RDQVxuKzdKdmphR3duUVFDSUVCSk1aVFJ3OVpnYVYzaUtPOEtrelhMOUxnZ1JKSGpuaUhVTnVqWTBNVlRcbi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS1cbg=="

externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"