report-management.yaml

openapi: "3.0.0"
info:
  description: "This is the Report API for UC4."
  version: "0.19.1"
  title: "UC4"

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

tags:
- name: "Version Management"
  description: "Everything about the Version"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"
- name: "Report Management"
  description: "Everything about the Reports"
  externalDocs:
    description: "Find out more"
    url: "https://github.com/upb-uc4"
- name: "Certificate Management"
  description: "Everything about Certificates"
  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/JsonVersionNumber'
  /certificates/{username}/enrollment:
    get:
      tags:
      - "Certificate Management"
      summary: "Get a user's certificate of enrollment"
      security:
        - uc4_token_login: [] 
        - uc4_token_login_header: []
      description: "Get a user's certificate of enrollment."
      operationId: "getEnrollmentCertificate"
      parameters:
      - name: "username"
        in: "path"
        description: "The user whose certificate of enrollment is requested"
        required: true
        schema:
          type: "string"
      - name: "semester"
        in: "query"
        description: "Base64Url encoded semester for which a certificate of enrollment is requested. If no semester is specified, a certificate for the latest semester will be generated."
        required: false
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "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: HLNotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "422":
          description: |
            Unprocessable Entity   
            types: LoginTokenSignatureInvalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
  /certificates/{username}/transcript_of_records:
    get:
      tags:
      - "Certificate Management"
      summary: "Get a user's signed transcript of records"
      security:
        - uc4_token_login: [] 
        - uc4_token_login_header: []
      description: "Get a user's signed transcript of records."
      operationId: "getTranscriptOfRecords"
      parameters:
      - name: "username"
        in: "path"
        description: "The user whose transcript of records is requested"
        required: true
        schema:
          type: "string"
      - name: "exam_reg_name"
        in: "query"
        description: "The name of the examination regulation, for which to create the transcript of records"
        required: true
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "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'
  /reports/{username}/archive:
    get:
      tags:
      - "Report Management"
      summary: "Get a User's report"
      security:
        - uc4_token_login: [] 
        - uc4_token_login_header: []
      description: "Get a user's report containing all their data stored in the system, both on chain and in database. On first call, such an archieve is prepared and a 202 is returned. If an archieve is currently present, the archive is returned."
      operationId: "getArchivedReport"
      parameters:
      - name: "username"
        in: "path"
        description: "The user whose archive is requested"
        required: true
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
          content:
            archive/*:
              schema:
                type: string
                format: binary
          headers:
            Content-Type:
              schema:
                type: string
              description: "content type and encoding"
            X-UC4-Timestamp:
              schema:
                type: string
              description: "Timestamp of when this resource was created"
            Cache-Control:
              schema:
                type: string
              description: "We do not want caching of the report resource"
        "202":
          description: "Accepted"
          headers:
            x-uc4-timestamp:
              schema:
                type: string
              description: "Timestamp of when this resource was created"
        "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'
    delete:
      tags:
      - "Report Management"
      summary: "Delete a user's report."
      security:
        - uc4_token_login: [] 
        - uc4_token_login_header: []
      description: "Delete a user's stored report. Does nothing if the report does not exist."
      operationId: "deleteArchivedReport"
      parameters:
      - name: "username"
        in: "path"
        description: "The user whose report is to be deleted"
        required: true
        schema:
          type: "string"
      responses:
        "200":
          description: "OK"
        "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'
components:
  securitySchemes:
    uc4_token_login:
      type: apiKey
      in: cookie
      name: login
    uc4_token_login_header:
      type: http
      scheme: bearer
  schemas:
    JsonVersionNumber:
      type: object
      properties:
        versionNumber:
          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
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"