openapi: 3.0.4
info:
  title: Public basic API for curricula backend module
  description: |-
    Charles University Study Information System (SIS) Open API specification for `curricula` backend module for obtaining study plans.
    
    - module name: `curricula`
    - 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}/curricula/publicApi/basic/1.0.0"
    description: API base URL
    variables:
      sisBase:
        description: SIS base URL
        default: http://localhost:8080


tags:
  - name: Curricula
    description: Operations provided on a Curriculum resource.


paths:
  /curricula/{curriculumCode}/subjects:
    get:
      tags:
        - Curricula
      summary: Get curriculum detail with subjects that are part of it.
      description: Provides full information about the curriculum and basic information about all subjects related to it. The curriculum is identified by its code and the academic year.
      operationId: getCurriculum
      parameters:
        - name: curriculumCode
          in: path
          description: Curriculum code
          required: true
          schema:
            type: string
            example: NIDAW22B
        - name: academicYear
          in: query
          description: Academic year in which the curriculum is valid. 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 curriculum 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 of accessing curriculum detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/curriculum'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Curriculum 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:
    curriculum:
      title: Curriculum
      description: >-
        Studijní plán stanovuje časovou, obsahovou návaznost studijních předmětů,
        formu výuky, povinné předměty, povinně volitelné předměty, volitelné předměty
        (i z jiných fakult či VŠ se kterými ma UK smlouvy). Obvykle mimo doktorská
        studia, kde je stanoven individuální studijní plán.
      type: object
      required:
        - code
        - academicYear
        - name
        - compulsorySubjects
        - electiveSubjects
        - optionalSubjects
        - finalExams
      properties:
        code:
          title: code
          description: Kód studijního plánu.
          type: string
          example: NIDAW22B
        academicYear:
          title: academic year
          description: Akademický rok platnosti plánu. Academic year is represented by the year in which it starts.
          type: integer
          pattern: ^[0-9]{4}$
          example: 2022
        name:
          title: name
          description: Název studijního plánu.
          allOf:
            - $ref: '#/components/schemas/languageString'
          example:
            cs: Databáze a web Bc. (2022)
            en: Databases and Web Bc. (2022)
        compulsorySubjects:
          title: compulsory subjects
          type: array
          items:
            $ref: '#/components/schemas/block'
        electiveSubjects:
          title: elective subjects
          type: array
          items:
            $ref: '#/components/schemas/electiveBlock'
        optionalSubjects:
          title: optional subjects
          type: array
          items:
            $ref: '#/components/schemas/block'
        finalExams:
          type: array
          items:
            title: Final exam
            description: Předmět, jež reprezentuje závěrečnou zkoušku.
            type: object
            required:
              - code
              - name
            properties:
              code:
                title: code
                description: Kód předmětu.
                type: string
              name:
                title: name
                description: Název předmětu.
                allOf:
                  - $ref: '#/components/schemas/languageString'

    block:
      title: Block of subjects in the curriculum
      description: >-
        Reprezentuje skupinu předmětů ve studijním plánu, která má název a pro povinně
        volitelné předměty určuje minimální počet kreditů. Blok může obsahovat další
        bloky nebo předměty, přičemž může obsahovat i obojí zároveň.
      type: object
      required:
        - name
        - recommendedYear
        - subjects
        - subblocks
      properties:
        name:
          title: name
          description: Název bloku.
          allOf:
            - $ref: '#/components/schemas/languageString'
        recommendedYear:
          title: recommended year
          description: Doporučený ročník studia plnění předmětů v bloku.
          type: number
          nullable: true
          minimum: 1
        subjects:
          title: subjects
          type: array
          items:
            $ref: '#/components/schemas/subject'    
        subblocks:
          title: subblocks
          type: array
          items:
            $ref: '#/components/schemas/block'

    electiveBlock:
      title: Block of elective subjects in the curriculum
      allOf:
        - $ref: '#/components/schemas/block'
        - type: object
          required:
            - minimumCredits
            - subblocks
          properties:
            minimumCredits:
              title: minimum credits
              description: Stanovuje minimální počet kreditů, které je nutné získat v celkovém součtu, aby byl blok považován za splněný.
              type: number
            subblocks:
              title: subblocks
              type: array
              items:
                $ref: '#/components/schemas/electiveBlock'

    subject:
      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
      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: NPRG030
        name:
          title: name
          description: Název předmětu v různých jazykových mutacích.
          allOf:
            - $ref: '#/components/schemas/languageString'
          example:
            cs: Programování 1
            en: Programming 1


    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