openapi: 3.0.3
info:
  description: 'The Lookup API provides a simple interface for applications that just want to retrieve a list of items. Using
    the Lookup API, clients can retrieve lists of level/semester codes, subjects, and schools used within Cardiff University.

    '
  version: v1
  title: LookupsApi
  termsOfService: http://www.cardiff.ac.uk/terms/
  contact:
    name: integration@cardiff.ac.uk
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.data.cardiff.ac.uk/lookups/v1
paths:
  /schools:
    get:
      tags:
      - Schools
      summary: Retrieve a list of all schools within the Univesity.
      parameters:
      - name: option
        in: query
        description: Options for selecting schools. "parent" for parent schools list
        required: false
        schema:
          type: string
      - name: code
        in: query
        description: Selecting schools by School code
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of schools to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Offset of schools to return
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Returns a list all schools
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      semesters:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            parent:
                              type: string
                            code:
                              type: string
                          required:
                          - code
                          - name
                          - parent
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
  /semesters:
    get:
      tags:
      - Semesters
      summary: Retrieve a list of all semesters used within the Univesity.
      parameters:
      - name: limit
        in: query
        description: Number of semesters to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Offset of semesters to return
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Returns a list all semesters
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      semesters:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            code:
                              type: string
                          required:
                          - code
                          - name
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
  /subjects:
    get:
      tags:
      - Subjects
      summary: Retrieve a list of all subjects taught within the Univesity.
      parameters:
      - name: type
        in: query
        description: 'Programme Type. Accepted values: P (Postgraduate), R (Research) or U (Undergraduate). (Note: This parameter
          is case sensitive.)'
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of subjects to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Offset of subjects to return
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Returns a list all subjects
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      subjects:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            code:
                              type: string
                          required:
                          - code
                          - name
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
  /levels:
    get:
      tags:
      - Levels
      summary: Retrieve a list of all available levels used within the Univesity.
      parameters:
      - name: limit
        in: query
        description: Number of levels to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Offset of levels to return
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Returns a list all Levels
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      levels:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            code:
                              type: string
                          required:
                          - code
                          - name
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
  /qualifications:
    get:
      tags:
      - Qualifications
      summary: Retrieve a list of all available qualifications used within the Univesity.
      parameters:
      - name: school
        in: query
        description: Returns qualifications linked to the specified school code e.g. SOCSI (Social Sciences)
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: 'Filters modules by programme type. Accepted values: P (Postgraduate), R (Research) or U (Undergraduate).
          (Note: This parameter is case sensitive.)'
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of qualifications to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Offset of qualifications to return
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Returns a list all Levels
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      levels:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            code:
                              type: string
                          required:
                          - code
                          - name
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
  /years:
    get:
      tags:
      - Years
      summary: Retrieve a list of academic years within the Univesity.
      parameters:
      - name: mode
        in: query
        description: Mode of retrieving the list of year. Options are "current","between" and "amount". For "current" mode,
          it returns the current academic year in a single object. For "between" mode, input parameters "from" and "to" are
          used. (e.g. "from=2023&to=2033"). For "amount" mode, input parameters "from" and "numofyears" are used. (e.g. "from=2023&numofyears=12").
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: Using with "between" or "amount" mode. Selected year to start from (e.g. 2023). Default value is current
          academic year.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: Using with "between" mode. Selected year to end (inclustive) (e.g. 2033).
        required: false
        schema:
          type: string
      - name: numofyears
        in: query
        description: Using with "amount" mode. Number of years to return. It can be a positive number (select N years forward)
          or a negative number (select N years backward) (e.g. 12, -12)
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Using without mode. Number of years to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Using without mode. Offset of years to return
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Returns a list of academic years
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      years:
                        type: array
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            name:
                              type: string
                            startDate:
                              type: string
                            endDate:
                              type: string
                            current:
                              type: boolean
                          required:
                          - code
                          - name
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
components:
  schemas:
    Meta:
      type: object
      required:
      - code
      - contentType
      - count
      - errorStatus
      properties:
        errorMessage:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
        count:
          type: integer
          format: int32
        code:
          type: integer
          format: int32
        contentType:
          type: string
        errorStatus:
          type: boolean
      title: meta
  securitySchemes:
    default:
      type: oauth2
      flows:
        implicit:
          scopes: {}
          authorizationUrl: https://api.data.cardiff.ac.uk/authorize
security:
- default: []