admission-management.yaml

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

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

tags:
- name: "Version Management"
  description: "Everything about the Version"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"
- name: "Admission Management"
  description: "Everything about the Admissions"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"
- name: "Course Admission Management"
  description: "Everything about the Course Admissions"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"
- name: "Exam Admission Management"
  description: "Everything about the Exam Admissions"
  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'
  /admissions/unsigned_add_proposal:
    post:
      tags:
      - "Admission Management"
      summary: "Fetch a proposal for admitting a student to a course or an exam"
      description: "Fetch a proposal for admitting the student to either the course or the exam specified by the object. AdmissionId, EnrollmentID and timestamp will be set in the returned proposal. Only invokable by Students."
      operationId: "getProposalAddAdmission"
      security:
        - uc4_token_login: []
        - uc4_token_login_header: []
      requestBody:
        description: "Admission object from which the proposal is constructed"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CourseAdmission'
            examples:
              AddCourseAdmission:
                $ref: '#/components/examples/ExampleCourseAdmissionPost'
              AddExamAdmission:
                $ref: '#/components/examples/ExampleExamAdmissionPost'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsignedProposal'
              examples:
                ExampleUnsignedProposal:
                  $ref: '#/components/examples/ExampleUnsignedProposal'
          headers:
            Location:
              schema:
                type: string
                description: "URI of the newly created Admission"
        "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'
  /admissions/unsigned_drop_proposal:
    post:
      tags:
      - "Admission Management"
      summary: "Fetch a proposal for dropping an Admission"
      description: "Fetch a proposal for dropping an Admission, using the parameters in the body."
      security:
        - uc4_token_login: [] 
        - uc4_token_login_header: []
      operationId: "getProposalDropAdmission"
      requestBody:
        description: "DropAdmission object, containing the AdmissionId of the admission to drop."
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DropAdmission'
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsignedProposal'
              examples:
                ExampleUnsignedProposal:
                  $ref: '#/components/examples/ExampleUnsignedProposal'
        "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'
        "404":
          description: |
            Not Found  
            types: KeyNotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "422":
            description: |
              Unprocessable Entity   
              types: LoginTokenSignatureInvalid
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/GenericError'
  /admissions/courses:
    get:
      tags:
      - "Course Admission Management"
      summary: "Get All Course Admissions"
      description: "When invoked by an Admin and without query parameters, returns all Course Admissions. When invoked with query parameters, returns Course Admissions filtered by the parameters."
      operationId: "getAllCourseAdmissions"
      parameters:
      - name: "username"
        in: "query"
        description: "Username for which to fetch the course admissions"
        required: false
        schema:
          type: "string"
      - name: "courseId"
        in: "query"
        description: "CourseId for which to fetch the course admissions"
        required: false
        schema:
          type: "string"
      - name: "moduleId"
        in: "query"
        description: "ModuleId for which to fetch the course admissions"
        required: false
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/CourseAdmission'
              examples:
                GetCourseAdmission:
                  $ref: '#/components/examples/ExampleCourseAdmissionGet'
        "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'
  /admissions/exams:
    get:
      tags:
      - "Exam Admission Management"
      summary: "Get All Exam Admissions"
      description: "When invoked by an Admin and without query parameters, returns all Exam Admissions. When invoked with query parameters, returns Exam Admissions filtered by the parameters."
      operationId: "getAllExamAdmissions"
      parameters:
      - name: "username"
        in: "query"
        description: "Username, whose enrollmentId to filter by"
        required: false
        schema:
          type: "string"
      - name: "admissionIds"
        in: "query"
        description: "Comma separated list of AdmissionIds to filter by"
        required: false
        schema:
          type: "string"
      - name: "examIds"
        in: "query"
        description: "Comma separated list of examIds to filter by"
        required: false
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  $ref: '#/components/schemas/ExamAdmission'
              examples:
                GetExamAdmission:
                  $ref: '#/components/examples/ExampleExamAdmissionGet'
        "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'
components:
  securitySchemes:
    uc4_token_login:
      type: apiKey
      in: cookie
      name: login
    uc4_token_login_header:
      type: http
      scheme: bearer
  schemas:
    AbstractAdmission:
      type: object
      properties:
        admissionId:
          type: string
        enrollmentId:
          type: string
        timestamp:
          type: string
          format: date
        type:
          type: string
          enum: [Course, Exam]
    CourseAdmission:
      allOf:
        - $ref: '#/components/schemas/AbstractAdmission'
        - type: object
          properties:
            courseId:
              type: string
            moduleId:
              type: string
    ExamAdmission:
     allOf:
        - $ref: '#/components/schemas/AbstractAdmission'
        - type: object
          properties:
            examId:
              type: string
    DropAdmission:
      type: object
      properties:
        admissionId:
          type: string
    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:
    ExampleCourseAdmissionPost:
      summary: "An example for a CourseAdmission object"
      value:
        admissionId: ""
        enrollmentId: ""
        timestamp: ""
        courseId: "eae27105-2fd5-11eb-ad58-572c5dfe1b7a"
        moduleId: "M.1275.01158"
        type: "Course"
    ExampleExamAdmissionPost:
      summary: "An example for an ExamAdmission object"
      value:
        admissionId: ""
        enrollmentId: ""
        timestamp: ""
        examId: "AnExampleExamId"
        type: "Exam"
    ExampleCourseAdmissionGet:
      summary: "An example for a list of filled course admissions"
      value:
        - admissionId: "e53143d725255d70945989901ebc137a7d35c2b61ffdfecb9a135c6136eea4a6:eae27105-2fd5-11eb-ad58-572c5dfe1b7a:M.1275.01158"
          enrollmentId: "e53143d725255d70945989901ebc137a7d35c2b61ffdfecb9a135c6136eea4a6"
          timestamp: "2020-12-01"
          type: "Course"
          courseId: "eae27105-2fd5-11eb-ad58-572c5dfe1b7a"
          moduleId: "M.1275.01158"
    ExampleExamAdmissionGet:
      summary: "An example for a list of filled exam admissions"
      value:
        - admissionId: "e53143d725255d70945989901ebc137a7d35c2b61ffdfecb9a135c6136eea4a6:AnExampleExamId"
          enrollmentId: "e53143d725255d70945989901ebc137a7d35c2b61ffdfecb9a135c6136eea4a6"
          timestamp: "2020-12-01"
          type: "Exam"
          examId: "AnExampleExamId"
    ExampleUnsignedProposal:
      summary: "Example for UnsignedProposal"
      value:
        unsignedProposal: "CpUJCmoIAxABGgsIgL22/AUQ+NbCWSIJbXljaGFubmVsKkBhMzUwNzA1YWNiMGVmNDUyMzQxN2RjYTRkMTA0ZDUxNmYzMmMxNTgwNzhiYTA4Yzk0NmU1OGRkZWIzZWJhYTJmOgoSCBIGdWM0LWNjEqYICokICgdvcmcxTVNQEv0HLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN4akNDQW0yZ0F3SUJBZ0lVYkFLNmdwb1BGaTQxeEloY1Z5YkdXZUV0cXpBd0NnWUlLb1pJemowRUF3SXcKWURFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVJFd0R3WURWUVFERXdoeVkyRXRiM0puCk1UQWVGdzB5TURFd01Ua3hNelU0TURCYUZ3MHlNVEV3TVRreE5EQXpNREJhTURneERqQU1CZ05WQkFzVEJXRmsKYldsdU1TWXdKQVlEVlFRREV4MXpZMkZzWVMxeVpXZHBjM1J5WVhScGIyNHRZV1J0YVc0dGIzSm5NVEJaTUJNRwpCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQktab1BNRVpYa1VUdHV3R3VZYmE3UWJHcWpxSFRuVnEyeGVDCklERG1kYmMyUkhBMjBEZjMwY3VUN1dHMVJzdGIyWmpoRS9ESWhVQjRlUzMwbkxTRFJobWpnZ0VyTUlJQkp6QU8KQmdOVkhROEJBZjhFQkFNQ0E2Z3dIUVlEVlIwbEJCWXdGQVlJS3dZQkJRVUhBd0VHQ0NzR0FRVUZCd01DTUF3RwpBMVVkRXdFQi93UUNNQUF3SFFZRFZSME9CQllFRk5pbndnNkRveXliS09veEUweENkT2VkOTUraE1COEdBMVVkCkl3UVlNQmFBRkhFN1lISTJwVFhRaWZ4R3o5c2l2cURYTGV1Yk1DZ0dBMVVkRVFRaE1CK0NIWE5qWVd4aExYSmwKWjJsemRISmhkR2x2YmkxaFpHMXBiaTF2Y21jeE1INEdDQ29EQkFVR0J3Z0JCSEo3SW1GMGRISnpJanA3SW1GawpiV2x1SWpvaWRISjFaU0lzSW1obUxrRm1abWxzYVdGMGFXOXVJam9pSWl3aWFHWXVSVzV5YjJ4c2JXVnVkRWxFCklqb2ljMk5oYkdFdGNtVm5hWE4wY21GMGFXOXVMV0ZrYldsdUxXOXlaekVpTENKb1ppNVVlWEJsSWpvaVlXUnQKYVc0aWZYMHdDZ1lJS29aSXpqMEVBd0lEUndBd1JBSWdZdUR6d0I2dU00RnhUTHdWVlRpeGcvWUFTS1U0a0RDQQorN0p2amFHd25RUUNJRUJKTVpUUnc5WmdhVjNpS084S2t6WEw5TGdnUkpIam5pSFVOdWpZME1WVAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tChIYTH47gBwXl+errTr7n7m2byTjHtQteNtsEssICsgICsUICAESCBIGdWM0LWNjGrYICh5VQzQuQ2VydGlmaWNhdGU6YWRkQ2VydGlmaWNhdGUKAzEwMQqOCC0tLS0tQkVHSU4gQ0VSVElGSUNBVEUtLS0tLVxuTUlJQ3hqQ0NBbTJnQXdJQkFnSVViQUs2Z3BvUEZpNDF4SWhjVnliR1dlRXRxekF3Q2dZSUtvWkl6ajBFQXdJd1xuWURFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ1lEVlFRS1xuRXd0SWVYQmxjbXhsWkdkbGNqRVBNQTBHQTFVRUN4TUdSbUZpY21sak1SRXdEd1lEVlFRREV3aHlZMkV0YjNKblxuTVRBZUZ3MHlNREV3TVRreE16VTRNREJhRncweU1URXdNVGt4TkRBek1EQmFNRGd4RGpBTUJnTlZCQXNUQldGa1xuYldsdU1TWXdKQVlEVlFRREV4MXpZMkZzWVMxeVpXZHBjM1J5WVhScGIyNHRZV1J0YVc0dGIzSm5NVEJaTUJNR1xuQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJLWm9QTUVaWGtVVHR1d0d1WWJhN1FiR3FqcUhUblZxMnhlQ1xuSUREbWRiYzJSSEEyMERmMzBjdVQ3V0cxUnN0YjJaamhFL0RJaFVCNGVTMzBuTFNEUmhtamdnRXJNSUlCSnpBT1xuQmdOVkhROEJBZjhFQkFNQ0E2Z3dIUVlEVlIwbEJCWXdGQVlJS3dZQkJRVUhBd0VHQ0NzR0FRVUZCd01DTUF3R1xuQTFVZEV3RUIvd1FDTUFBd0hRWURWUjBPQkJZRUZOaW53ZzZEb3l5YktPb3hFMHhDZE9lZDk1K2hNQjhHQTFVZFxuSXdRWU1CYUFGSEU3WUhJMnBUWFFpZnhHejlzaXZxRFhMZXViTUNnR0ExVWRFUVFoTUIrQ0hYTmpZV3hoTFhKbFxuWjJsemRISmhkR2x2YmkxaFpHMXBiaTF2Y21jeE1INEdDQ29EQkFVR0J3Z0JCSEo3SW1GMGRISnpJanA3SW1Ga1xuYldsdUlqb2lkSEoxWlNJc0ltaG1Ma0ZtWm1sc2FXRjBhVzl1SWpvaUlpd2lhR1l1Ulc1eWIyeHNiV1Z1ZEVsRVxuSWpvaWMyTmhiR0V0Y21WbmFYTjBjbUYwYVc5dUxXRmtiV2x1TFc5eVp6RWlMQ0pvWmk1VWVYQmxJam9pWVdSdFxuYVc0aWZYMHdDZ1lJS29aSXpqMEVBd0lEUndBd1JBSWdZdUR6d0I2dU00RnhUTHdWVlRpeGcvWUFTS1U0a0RDQVxuKzdKdmphR3duUVFDSUVCSk1aVFJ3OVpnYVYzaUtPOEtrelhMOUxnZ1JKSGpuaUhVTnVqWTBNVlRcbi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS1cbg=="

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