openapi: 3.0.4
info:
  title: Public basic API for schedule backend module
  description: |-
    Charles University Study Information System (SIS) Open API specification for `schedule` backend module for obtaining information about school subject, person and building schedules, reservations and other events.
    
    - module name: `schedule`
    - 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}/schedule/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 on a Subject resource.
  - name: Persons
    description: Operations provided on Person resource.
  - name: Buildings and Rooms 
    description: Operations provided on Buildings and Rooms.
  - name: Student groups
    description: Operations provided on Student groups.

paths:

  /subjects/{subjectCode}:
    get:
      summary: Get subject scheduling information
      description: Provides aggregated information about a subject's scheduling.
      tags:
        - Subjects
      parameters:
        - name: subjectCode
          in: path
          description: Subject code
          required: true
          schema:
            type: string
            example: CNT026P2
        - $ref: '#/components/parameters/academicYear'
        - $ref: '#/components/parameters/semester'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subject'
        '400':
          description: Invalid query 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'

  /subjects/{subjectCode}/semesterSchedule:
    get:
      summary: Get subject's schedule
      description: Get a complete schedule for a given subject in the academic year and semester. If the academic year and a semester is missing, the current is used.
      tags:
        - Subjects
      parameters:
        - name: subjectCode
          in: path
          description: Subject code
          required: true
          schema:
            type: string
            example: CNT026P2
        - $ref: '#/components/parameters/academicYear'
        - $ref: '#/components/parameters/semester'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule'
        '400':
          description: Invalid query 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'

  /teachers/{personalNumber}/schedule:
    get:
      summary: Get teacher's schedule
      description: Get a complete public schedule for a given teacher for the given time period.
      tags:
        - Persons
      parameters:
        - name: personalNumber
          in: path
          description: Personal number (UKČO) of the Teacher (Person)
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Teacher not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'

  /teachers/{personalNumber}/semesterSchedule:
    get:
      summary: Get teacher's schedule
      description: Get a complete public schedule for a given teacher in the academic year and semester across all faculties. If the academic year and a semester is missing, the current is used.
      tags:
        - Persons
      parameters:
        - name: personalNumber
          in: path
          description: Personal number (UKČO) of the Teacher (Person)
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/academicYear'
        - $ref: '#/components/parameters/semester'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Teacher not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        
  /rooms/{roomCode}/schedule:
    get:
      tags:
        - Buildings and Rooms
      summary: Get room's schedule
      description: Get a complete schedule for a given room for the given time period.
      parameters:
        - name: roomCode
          in: path
          description: Room code
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Room not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
  /rooms/{roomCode}/semesterSchedule:
    get:
      tags:
        - Buildings and Rooms
      summary: Get rooms's schedule
      description: Get a complete schedule for a given room in the academic year and semester across all faculties. If the academic year and a semester is missing, the current is used.
      parameters:
        - name: roomCode
          in: path
          description: Room code
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/academicYear'
        - $ref: '#/components/parameters/semester'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '404':
          description: Room not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'

  /studentGroups/semesterSchedule:
    get:
      summary: Get student group's schedule
      description: Get a complete schedule for a given student group in the academic year and semester. If the academic year and a semester is missing, the current is used.
      tags:
        - Student groups
      parameters:
        # Faculty, academic year, and semester
        - in: query
          name: faculty
          description: Faculty id
          required: true
          schema:
            type: string
            example: "11320"
        - $ref: '#/components/parameters/academicYear'
        - $ref: '#/components/parameters/semester'

        # Individual student group parameters
        - in: query
          name: typeOfStudy
          description: Druh studia pro účely zobrazování rozvrhů je nastavován rozvrháři jako odvození z akreditovaných druhů studia. 
          required: false
          schema:
            type: string
        - in: query
          name: studyProgramme
          description: Studijní programy pro účely zobrazování rozvrhů jsou nastavovány rozvrháři jako odvození z akreditovaných studijních programů.
          required: false
          schema:
            type: string
        - in: query
          name: year
          description: Ročník pro účely zobrazování rozvrhů je nastavován rozvrháři.
          required: false
          schema:
            type: string
        - in: query
          name: branch
          description: Studijní obory pro účely zobrazování rozvrhů jsou nastavovány rozvrháři.
          required: false
          schema:
            type: string
        - in: query
          name: combination
          description: Kombinace studijních programů pro účely zobrazování rozvrhů jsou nastavovány rozvrháři a mohou být odvozeny z akreditovaných kombinací studijních programů.
          required: false
          schema:
            type: string
        - in: query
          name: specialization
          description: Specializace pro účely zobrazování rozvrhů jsou nastavovány rozvrháři a mohou být odvozeny z akreditovaných specializací. 
          required: false
          schema:
            type: string
        - in: query
          name: studentClass
          description: "Jedná se o skupinu studentů, která se účastní konkrétní výuky společně. Může se skládat z několika kruhů. Označuje se kódem např.: BcI1-X. V rámci rozvrhů se jedná o paralelky pro účely zobrazování rozvrhů, které jsou nastavovány rozvrháři jako odvození z oficiálního seznamu paralelek."
          required: false
          schema:
            type: string
        # Půlparalelka parameter is deprecated
        - in: query
          name: circle
          description: Kruh je skupina studentů označená číslem. V rámci rozvrhů se jedná o kruhy pro účely zobrazování rozvrhů, které jsou nastavovány rozvrháři jako odvození z oficiálního seznamu kruhů. 
          required: false
          schema:
            type: string
        - in: query
          name: language
          description: Jazyk výuky pro účely zobrazování rozvrhů je nastavován rozvrháři. 
          required: false
          schema:
            type: string
        - in: query
          name: sortOfStudy
          description: Jedná se o formu v jaké je realizována výuka např. denní, kombinovaná. V rámci rozvrhů se jedná o formy výuky pro účely zobrazování rozvrhů, které jsou nastavovány rozvrháři jako odvození z oficiálního seznamu způsobů výuky.
          required: false
          schema:
            type: string
        
        
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schedule'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'

components:
  schemas:
    subject:
      title: Subject
      description: Aggregated information about a subject's scheduling.
      type: object
      required:
        - code
        - teachers
        - languages
        - primaryParallels
        - secondaryParallels
      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
        teachers:
          title: Teachers
          description: List of teachers actually teaching the subject. This means that at least one parallel is taught by the given teacher.
          type: array
          items:
            $ref: '#/components/schemas/person'
        languages:
          title: Languages
          description: List of languages in which the subject is actually taught. This means that at least one parallel is taught in the given language.
          type: array
          items:
            type: string
            example: cs
        primaryParallels:
          title: Number of primary parallels for the subject for informational purposes.
          type: number
          minimum: 0
          nullable: true
        secondaryParallels:
          title: Number of secondary parallels for the subject for informational purposes.
          type: number
          minimum: 0
          nullable: true

    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

    schedule:
      title: Collection of events.
      type: array
      items:
        $ref: '#/components/schemas/event'

    event:
      title: Event
      description: Událost reprezentuje soubor konání jedné akce v různých časech. Může se například jednat o rezervaci, která se opakuje pravidelně, nebo o výuku předmětu.
      type: object
      required:
        - type
        - code
        - note
        - layouts
      properties:
        type:
          type: string
          enum: ["parallel", "reservation"]
        code:
          title: Code
          type: string
        note:
          title: Note
          type: string
          nullable: true
        layouts:
          type: array
          items:
            $ref: '#/components/schemas/eventLayout'
    reservation:
      title: Rezervace
      description: Jedná se o blokování místa a času.
      allOf:
        - $ref: '#/components/schemas/event'
        - type: object
          required:
          - type
          - name
          - description
          properties:
            type:
              type: string
              enum: ["reservation"]
            name:
              title: Name
              description: Pojmenování rezervace
              allOf:
                - $ref: '#/components/schemas/languageString'
            description:
              title: Description
              description: Specifikace nebo upřesnění rezervace
              allOf:
                - $ref: '#/components/schemas/languageString'
    parallel:
      title: Parallel
      description: Paralelky označují ekvivalentní soubory hodin, v nichž se realizuje shodná
        výuka.
      allOf:
        - $ref: '#/components/schemas/event'
        - type: object
          required:
          - type
          - code
          - academic_year
          - language
          - public_note
          properties:
            type:
              type: string
              enum: ["parallel"]
            academic_year:
              title: Academic Year
              type: string
            language:
              title: Language
              description: V jakém jazyce je vedena výuka
              type: string
            public_note:
              title: Public Note
              allOf:
                - $ref: '#/components/schemas/languageString'
            subject:
              $ref: '#/components/schemas/subjectBasic'

    subjectBasic:
      type: object

    eventLayout:
      title: Event layout
      description: Popisuje konání dané události (výuky, konzultace, rezervace) které lze opakovat, vázat na výukové hodiny v rámci semestru, nebo kalendářního roku. Kompletní popis konání události lze pak popsat několika rozvrženími.
      type: object
      required:
        - type
        - beginTime
        - endTime
        - weeks
        - isEverySecondWeek
        - dayInWeek
        - isOnline
      properties:
        type:
          type: string
          enum: ["semesterEventLayout", "yearEventLayout"]
        beginTime:
          title: Begin Time
          description: Čas začátku
          type: number
        endTime:
          title: End Time
          description: Čas konce
          type: number
        weeks:
          title: Weeks
          description: Kolik týdnů se bude událost opakovat
          type: number
          minimum: 1
        isEverySecondWeek:
          title: Is every second week
          description: Jestli se událost opakuje jendou za 14 dní
          type: boolean
        dayInWeek:
          title: Day in week
          type: number
        isOnline:
          title: Is online
          description: Určuje online výuku
          type: boolean
    semesterEventLayout:
      title: Semester Event
      description: Rozvrhový lístek s možností specifikace rozvrhu jednosemestrálního předmětu.
      allOf:
        - $ref: '#/components/schemas/eventLayout'
        - type: object
          required:
          - type
          - semester
          - academicYear
          - weekNumber
          properties:
            type:
              type: string
              enum: ["semesterEventLayout"]
            semester:
              title: Semester
              type: string
            academicYear:
              type: string
            weekNumber:
              title: První číslo týdne
              type: number
    yearEventLayout:
      title: Semester Event
      description: Rozvrhový lístek s možností specifikace rozvrhu jednosemestrálního předmětu.
      allOf:
        - $ref: '#/components/schemas/eventLayout'
        - type: object
          title: Year Event
          description: Rozvrhový lístek s možností specifikace rozvrhu dvousemestrálního předmětu.
          required:
          - type
          - year
          - weekNumber
          properties:
            type:
              type: string
              enum: ["yearEventLayout"]
            year:
              title: Year
              description: Kalendářní rok
              type: string
            weekNumber:
              title: Week number
              description: Pořadové číslo týdne v kalendářním roce
              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
  parameters:
    academicYear:
      in: query
      name: academicYear
      description: Academic year for which to view the schedule. If it is not set together with the semester, the current will be used.
      required: false
      schema:
        type: integer
        description: Academic year is represented by the year number in which it starts.
        pattern: ^[0-9]{4}$
        example: 2022
    semester:
      in: query
      name: semester
      description: Semester for which to view the schedule. If it is not set together with the semester, the current will be used.
      required: false
      schema:
        type: string
        enum:
          - winter
          - summer
    from:
      in: query
      name: from
      description: Start of the time interval for which to view the schedule.
      required: true
      schema:
        type: string
        format: date-time
        example: 2022-01-01T00:00:00+01:00
    to:
      in: query
      name: to
      description: End of the time interval for which to view the schedule.
      required: true
      schema:
        type: string
        format: date-time
        example: 2022-01-01T00:00:00+01:00
