openapi: 3.0.4
info:
  title: Public basic API for subjects backend module
  description: |-
    Charles University Study Information System (SIS) Open API specification for `subjects` backend module for obtaining information about school subjects and detailed info.
    
    - module name: `subjects`
    - specification name: `basic`
    - API version: `1.0.x`
    
    Please also check *Obecná technická specifikace* Word document and a list of concepts for complete specification.
    
    # State of this API
    
    Parts from the specification that are missing were either forgotten or omitted because they were not known during the writing of this specification. Please contact the authors if you think something important is missing.
    
    # Use of API
    
    The API uses standard HTTP status codes to indicate the success or failure of the API call. `2xx` means success of the operation, `4xx` means an error on the caller side. HTTP `5xx` return codes are used for internal errors on the callee side - SIS backend module or SIS infrastructure. It is important NOT to treat this as a failure operation; the execution status is UNKNOWN and could have been a success. The response of `4xx` and SOME `5xx` operations is an `apiError` object.
    
    This API is versioned to ensure that clients don't break. We use semantic versioning with the patch version used only for cosmetic changes in the specification document, not the interface itself. Therefore, APIs with identical major and minor versions are considered the same. Each API provider MUST support older API versions until they are marked as deprecated. If the version is not supported (meaning the major or minor version differs), the endpoint MUST return HTTP `400`, informing that the API version is either deprecated or unknown.
    
    The API uses an open schema model, which means callee may add extra properties to responses. Caller MUST ignore those additional properties. Likewise, the server MUST ignore any extra query parameters and request body properties.
    
    This specification intentionally omits any requirements enforced globally in *Obecná technická specifikace* Word document, such as passing correlation id, user info, or access token, as those depend on the context the caller and callee are in.
  version: 1.0.0


servers:
  - url: "{sisBase}/subjects/publicApi/basic/1.0.0"
    description: API base URL
    variables:
      sisBase:
        description: SIS base URL
        default: http://localhost:8080


tags:
  - name: Subjects
    description: Operations provided a Subject resource.


paths:
  /subjects:
    get:
      tags:
        - Subjects
      summary: Search subjects
      description: Searches subjects by only basic search parameters and returns their basic information.
      operationId: searchSubjects
      parameters:
        - in: query
          name: academicYear
          description: Shows subjects in the context of the given academic year. Academic year is represented by the year in which it starts. If the academic year is not provided, the current academic year is used.
          required: false
          schema:
            type: integer
            pattern: ^[0-9]{4}$
            example: 2020
        - in: query
          name: searchQuery
          description: Filters by search text. See the `extendedSearchQuery` parameter for more information.
          required: false
          schema:
            type: string
            example: math
        - in: query
          name: extendedSearchQuery
          description: If set, `searchQuery` is used in more fields than just the subject name. This document does not specify the scope of the extended search.
          required: false
          schema:
            type: boolean
        - in: query
          name: faculty
          description: If set, filters by faculty ID. If you provide multiple entries, results that match at least one of them will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              example: "11320"
        - in: query
          name: department
          description: If set, filters by department ID. If you provide multiple entries, results that match at least one of them will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              example: 32-KSI
        - in: query
          name: studyType
          description: If set, filters by the type of study. If you provide multiple entries, results that match at least one of them will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              example: B
        - in: query
          name: teachingType
          description: If set, filters by the form of teaching. If you provide multiple entries, results that match at least one of them will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - P
                - K
                - D
        - in: query
          name: language
          description: If set, filters by the language of teaching. If you provide multiple entries, results that match at least one of them will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              example: CZE
        - in: query
          name: semester
          description: If set, filters by the semester in which the subject begins. If you provide multiple entries, results that match at least one of them will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - winter
                - summer

        - in: query
          name: _offset
          description: Standard paging criterion for the beginning of the collection listing. If not provided, the collection is listed from the beginning.
          required: false
          schema:
            type: integer
            minimum: 0
        - in: query
          name: _limit
          description: Standard paging criterion for the number of elements in the collection listing. If not provided, all elements are listed.
          required: false
          schema:
            type: integer
            minimum: 1
        - in: query
          name: _orderBy
          description: Standard criterion for ordering elements.
          required: false
          schema:
            type: string
            enum:
              - searchQueryRelevance
              - name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/collection'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/subjectBasic'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
  /subjects/{subjectCode}:
    get:
      tags:
        - Subjects
      summary: Get specific subject
      description: Provides full information about specific subject identified by its code and academic year, if provided.
      operationId: getSubject
      parameters:
        - name: subjectCode
          in: path
          description: Subject code
          required: true
          schema:
            type: string
            example: CNT026P2
        - name: academicYear
          in: query
          description: Academic year is represented by the year in which it starts. If the academic year is not provided, the current academic year is used. If the subject is not valid for the given year, the response is HTTP `404`.
          required: false
          schema:
            type: integer
            pattern: ^[0-9]{4}$
            example: 2022
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subject'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Subject not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'


components:
  schemas:
    subject:
      allOf:
        - $ref: '#/components/schemas/subjectBasic'
        - type: object
          required:
            - subtitle
            - minimalCapacity
            - virtualMobility
            - hasPracticalTraining
            - virtualMobilityCapacity
            - forStudentsOfAnotherFaculty
            - taughtByAnotherFaculty
            - canBeEnrolledRepeatedly
            - intendedForDoctoralStudentsOnly
            - medicalCertificateRequired
            - maximumCapacity
            - guarantor
          properties:
            subtitle:
              title: Subtitle
              description: Text, který doplňuje název předmětu.
              nullable: true
              allOf:
                - $ref: '#/components/schemas/languageString'
            minimalCapacity:
              title: Minimal capacity
              description: Minimální počet zapsaných studentů na předmět, aby mohl být vyučován.
              nullable: true
              type: number
            virtualMobility:
              title: Virtual mobility
              description: Určuje, zda je předmět zapojen do programu 4EU+.
              type: boolean
            hasPracticalTraining:
              title: Has Practical Training
              description: Určuje, zda je součástí výuky v daném předmětu praxe.
              type: boolean
            virtualMobilityCapacity:
              title: Virtual mobility capacity
              description: Jedná se o počet míst určený pro virtuální mobilitu z celkové kapacity.
              type: number
            forStudentsOfAnotherFaculty:
              title: for students of another faculty
              description: Určuje, zda je předmět vyučován pro studenty jiné fakulty.
              type: boolean
            taughtByAnotherFaculty:
              title: taught by another faculty
              description: Výuka je garantována jinou fakultou, než je fakulta předmětu
              type: boolean
            canBeEnrolledRepeatedly:
              title: can be enrolled repeatedly
              description: Určuje, zda je možné předmět zapsat víc než jednou.
              type: boolean
            intendedForDoctoralStudentsOnly:
              title: intended for doctoral students only
              type: boolean
            medicalCertificateRequired:
              title: Medical certificate required
              description: Aby bylo možno studovat předmět, je potřeba doložit lékařské potvrzení.
              type: boolean
            maximumCapacity:
              title: maximum capacity
              description: Maximální kapacita předmětu, pokud není určena kapacitou rozvrhových
                lístků.
              nullable: true
              type: number

            guarantor:
              title: Subject Guarantor
              type: array
              items:
                $ref: '#/components/schemas/person'

    subjectBasic:
      title: Subject
      description: Předmět je oblast studia, která se na univerzitě vyučuje zejména v podobě
        přednášky, cvičení, semináře, prosemináře, kurzu, praxe, stáže, soustředění, laboratorní
        práce, exkurze, terénní práce, samostatné práce nebo konzultace. Předmět může být
        v závislosti na svém charakteru uskutečňován prezenční, kombinovanou nebo distanční
        formou. Mezi předměty řadíme i samostatné zkoušky které lze během studia splnit.
      type: object
      required:
        - code
        - name
        - credits
        - semester
        - yearlyWorkload
        - language
        - website
        - state
        - teachingType
        - faculty
        - semesters
      properties:
        code:
          title: Code
          description: Každému předmětu je přiřazen identifikační kód, který je v rámci
            univerzity jedinečný bez závislosti na období.
          type: string
          example: CNT026P2
        name:
          title: Name
          description: Název předmětu v různých jazykových mutacích.
          allOf:
            - $ref: '#/components/schemas/languageString'
        credits:
          title: Credits
          description: Počet kreditů jež student získá absolvováním daného předmětu, kterým
            se rozumí úspěšné splnění studijní povinnosti. Pokud je předmět dvousemestrální,
            jedná se o celkový počet kreditů získaných za oba semestry.
          type: number
          minimum: 0
        semester:
          type: array
          items:
            title: Je vyučován v
            description: "Do jakého semestru lze předmět zapsat. Pokud lze předmět zapsat
              v obou semestrech, pak tato hodnota bude obsahovat oba semestry. Pro vícesemestrální
              předměty se uvádí pouze zimní semestr, protože v letním semestru již předmět
              zapsat nelze."
            type: string
            enum:
              - winter
              - summer
        yearlyWorkload:
          title: yearly workload
          allOf:
            - $ref: '#/components/schemas/workload'
        language:
          title: Language
          description: Jazyky, ve kterých je předmět vyučován. Skutečný jazyk výuky je pak
            veden u konkrétní paralelky.
          type: array
          items:
            title: String
            type: string
        website:
          title: Website
          description: Webová stránka předmětu mimo SIS, jež může obsahovat doplňující informace
            a materiály. Nejedná se o stránky jednotlivých cvičících.
          type: string
          format: uri
          nullable: true
        state:
          title: State of the subject
          description: Stav předmětu pro variantu předmětu platnou v daném akademickém roce
          type: string
          enum:
            - N # nevyučován
            - Z # zrušen
            - V # vyučován
        teachingType:
          title: Teaching type
          description: Forma uskutečňování výuky předmětu.
          type: string
          enum:
            - P # prezenční
            - K # kombinovaná
            - D # distanční

        faculty:
          title: Faculty or Faculty Unit
          description: Fakulta, která zajišťuje předmět.
          allOf:
            - $ref: '#/components/schemas/faculty'

        semesters:
          type: array
          minItems: 1
          maxItems: 2
          items:
            title: Semester of Subject
            description: 'Pomocný koncept pro možnost zachycení předmětů, jež jsou dvousemestrální - ty pak mají dva koncepty "Semestr předmětu" v daném pořadí. Začátek a konec semestru se řídí aktuálně platným harmonogramem akademického roku, který je vydán jako opatřením rektora / děkana.'
            type: object
            required:
            - primaryWorkload
            - secondaryWorkload
            - selfStudyWorkload
            - examinationType
            - examinationProcess
            properties:
              primaryWorkload:
                title: Primary workload
                description: Rozsah výuky primární části předmětu, obvykle přednášky.
                allOf:
                  - $ref: '#/components/schemas/workload'
              secondaryWorkload:
                title: Secondary workload
                description: Rozsah výuky sekundární části předmětu, obvykle cvičení.
                allOf:
                  - $ref: '#/components/schemas/workload'
              selfStudyWorkload:
                title: Self-study workload
                description: Počet hodin nekontaktní výuky (samostudia) pro daný semestr předmětu.
                allOf:
                  - $ref: '#/components/schemas/workload'
              examinationType:
                title: Examination
                description: Popisuje způsob, jakým je předmět, případně závěrečná zkouška, zakončena. Předmět může být zakončen i některými kombinacemi examinací.
                type: array
                items:
                  type: string
              examinationProcess:
                title: Examination process
                type: string
                nullable: true

    collection:
      description: Collection of resources with paging information.
      type: object
      required:
        - paging
        - items
      properties:
        paging:
          description: Paging information.
          type: object
          required:
            - offset
            - limit
            - total
          properties:
            offset:
              description: Offset of the first element in the collection.
              type: integer
              minimum: 0
              example: 0
            limit:
              description: Maximum number of elements in the collection.
              type: integer
              minimum: 1
              example: 100
            total:
              description: Total number of elements in the collection.
              type: integer
              minimum: 0
              example: 477
        items:
          description: Embedded resources.

    workload:
      type: object
      title: Workload
      properties:
        value:
          type: number
          minimum: 0
        unit:
          type: string
          enum:
            - DS # days/semester
            - HS # hours/semester
            - HT # hours/week
            - TS # weeks/semester

    faculty:
      title: Faculty or Faculty Unit
      description: Fakulta uskutečňuje nejméně jeden akreditovaný studijní program a vykonává tvůrčí činnost.
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          example: 11320
        name:
          title: Name
          allOf:
            - $ref: '#/components/schemas/languageString'
          example:
            cs: Matematicko-Fyzikální fakulta
            en: Faculty of Mathematics and Physics

    person:
      title: Person
      type: object
      required:
      - firstName
      - familyName
      - degreePreceding
      - degreeAppended
      - email
      properties:
        firstName:
          title: First Name
          type: string
        familyName:
          title: Family Name
          type: string
        degreePreceding:
          title: Degree preceding
          description: Titul před jménem
          type: string
        degreeAppended:
          title: Degree appended
          description: Titul za jménem
          type: string
        email:
          title: Email
          type: string
        profilePhoto:
          title: Profile photo
          description: URL adresa profilové fotografie osoby
          type: string

    languageString:
      description: Key/value dictionary containing text translated to different languages. Keys are ISO 639-1 codes or "_" if the language is not known.
      type: object
      additionalProperties:
        type: string
      example:
        cs: Univerzita Karlova
        en: Charles University
        la: Universitas Carolina
        _: Univerzita Karlova

    apiError:
      description: Error response returned by the API. The list of error codes is not present in this specification. Please note that in case of critical errors, the response may be blank or may not match the schema.
      type: object
      required:
        - _errorCode
        - _errorMessage
      properties:
        _errorCode:
          description: Error code.
          type: string
        _errorMessage:
          description: Human-readable error description.
          type: string