Al-Farabi Kazakh National University Courses API

openapi: 3.2.0
info:
  title: Open edX Courses API
  description: APIs for access to Open edX information
  contact:
    email: dl@kaznu.kz
  version: v1
servers:
- url: https://open.kaznu.kz/api
security:
- Basic: []
tags:
- name: Courses
paths:
  /courses/v1/block_metadata/{usage_key_string}:
    get:
      operationId: courses_v1_block_metadata_read
      summary: '**Use Case**'
      description: 'Returns the block metadata. Data like index_dictionary related to a

        block should be fetched using this API, because they are too large for

        the cache used by the course blocks/transformers API.


        **Example requests**:


        GET /api/courses/v1/block_metadata//?

        &include=index_dictionary


        **Parameters**:


        * "include": a comma-separated list of keys to include.

        Valid keys are "index_dictionary".


        **Response Values**


        A dictionary containing:

        * id (string): Block usage_key_str.

        * type (string) Block type.

        * index_dictionary: (dict) The index_dictionary JSON data

        (usually this is the text content of the block, for search

        indexing or other purposes) for this block. Returned only if

        the "index_dictionary" is included in the "include"

        parameter.'
      tags:
      - Courses
      parameters:
      - name: usage_key_string
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
  /courses/v1/blocks/:
    get:
      operationId: courses_v1_blocks_list
      summary: '**Use Case**'
      description: 'Returns the blocks in the course according to the requesting user''s

        access level.


        **Example requests**:


        GET /api/courses/v1/blocks/?course_id=

        GET /api/courses/v1/blocks/?course_id=

        &username=anjali

        &depth=all

        &requested_fields=graded,format,student_view_multi_device,lti_url

        &block_counts=video

        &student_view_data=video

        &block_types_filter=problem,html


        **Parameters**:


        This view redirects to /api/courses/v1/blocks// for the

        root usage key of the course specified by course_id. The view accepts

        all parameters accepted by :class:`BlocksView`, plus the following

        required parameter


        * course_id: (string, required) The ID of the course whose block data

        we want to return


        **Response Values**


        Responses are identical to those returned by :class:`BlocksView` when

        passed the root_usage_key of the requested course.


        If the course_id is not supplied, a 400: Bad Request is returned, with

        a message indicating that course_id is required.


        If an invalid course_id is supplied, a 400: Bad Request is returned,

        with a message indicating that the course_id is not valid.'
      tags:
      - Courses
      parameters:
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
  /courses/v1/blocks/{usage_key_string}:
    get:
      operationId: courses_v1_blocks_read
      summary: '**Use Case**'
      description: 'Returns the blocks within the requested block tree according to the

        requesting user''s access level.'
      tags:
      - Courses
      parameters:
      - name: usage_key_string
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
  /courses/v1/course_ids/:
    get:
      operationId: courses_v1_course_ids_list
      summary: '**Use Cases**'
      description: 'Request a list of course IDs for all courses the specified user can

        access based on the provided parameters.


        **Example Requests**


        GET /api/courses/v1/courses_ids/


        **Response Values**


        Body comprises a list of course ids and pagination details.


        **Parameters**


        username (optional):

        The username of the specified user whose visible courses we

        want to see.


        role (required):

        Course ids are filtered such that only those for which the

        user has the specified role are returned. Role can be "staff"

        or "instructor".

        Case-insensitive.


        **Returns**


        * 200 on success, with a list of course ids and pagination details

        * 400 if an invalid parameter was sent or the username was not provided

        for an authenticated request.

        * 403 if a user who does not have permission to masquerade as

        another user who specifies a username other than their own.

        * 404 if the specified user does not exist, or the requesting user does

        not have permission to view their courses.


        Example response:


        {

        "results":

        [

        "course-v1:edX+DemoX+Demo_Course"

        ],

        "pagination": {

        "previous": null,

        "num_pages": 1,

        "next": null,

        "count": 1

        }

        }'
      tags:
      - Courses
      parameters:
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      type: string
  /courses/v1/courses/:
    get:
      operationId: courses_v1_courses_list
      summary: '**Use Cases**'
      description: 'Request information on all courses visible to the specified user.


        **Example Requests**


        GET /api/courses/v1/courses/


        **Response Values**


        Body comprises a list of objects as returned by `CourseDetailView`.


        **Parameters**


        search_term (optional):

        Search term to filter courses (used by ElasticSearch).


        username (optional):

        The username of the specified user whose visible courses we

        want to see. The username is not required only if the API is

        requested by an Anonymous user.


        org (optional):

        If specified, visible `CourseOverview` objects are filtered

        such that only those belonging to the organization with the

        provided org code (e.g., "HarvardX") are returned.

        Case-insensitive.


        permissions (optional):

        If specified, it filters visible `CourseOverview` objects by

        checking if each permission specified is granted for the username.

        Notice that Staff users are always granted permission to list any

        course.


        active_only (optional):

        If this boolean is specified, only the courses that have not ended or do not have any end

        date are returned. This is different from search_term because this filtering is done on

        CourseOverview and not ElasticSearch.


        course_keys (optional):

        If specified, it fetches the `CourseOverview` objects for the

        the specified course keys


        mobile_search (bool):

        Optional parameter that limits the number of returned courses

        to MOBILE_SEARCH_COURSE_LIMIT.


        **Returns**


        * 200 on success, with a list of course discovery objects as returned

        by `CourseDetailView`.

        * 400 if an invalid parameter was sent or the username was not provided

        for an authenticated request.

        * 403 if a user who does not have permission to masquerade as

        another user specifies a username other than their own.

        * 404 if the specified user does not exist, or the requesting user does

        not have permission to view their courses.


        Example response:


        [

        {

        "blocks_url": "/api/courses/v1/blocks/?course_id=edX%2Fexample%2F2012_Fall",

        "media": {

        "course_image": {

        "uri": "/c4x/edX/example/asset/just_a_test.jpg",

        "name": "Course Image"

        }

        },

        "description": "An example course.",

        "end": "2015-09-19T18:00:00Z",

        "enrollment_end": "2015-07-15T00:00:00Z",

        "enrollment_start": "2015-06-15T00:00:00Z",

        "course_id": "edX/example/2012_Fall",

        "name": "Example Course",

        "number": "example",

        "org": "edX",

        "start": "2015-07-17T12:00:00Z",

        "start_display": "July 17, 2015",

        "start_type": "timestamp"

        }

        ]'
      tags:
      - Courses
      parameters:
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Course'
  /courses/v1/courses/{course_key_string}:
    get:
      operationId: courses_v1_courses_read
      summary: '**Use Cases**'
      description: 'Request details for a course


        **Example Requests**


        GET /api/courses/v1/courses/{course_key}/


        **Response Values**


        Body consists of the following fields:


        * effort: A textual description of the weekly hours of effort expected

        in the course.

        * end: Date the course ends, in ISO 8601 notation

        * enrollment_end: Date enrollment ends, in ISO 8601 notation

        * enrollment_start: Date enrollment begins, in ISO 8601 notation

        * id: A unique identifier of the course; a serialized representation

        of the opaque key identifying the course.

        * media: An object that contains named media items. Included here:

        * course_image: An image to show for the course. Represented

        as an object with the following fields:

        * uri: The location of the image

        * name: Name of the course

        * number: Catalog number of the course

        * org: Name of the organization that owns the course

        * overview: A possibly verbose HTML textual description of the course.

        Note: this field is only included in the Course Detail view, not

        the Course List view.

        * short_description: A textual description of the course

        * start: Date the course begins, in ISO 8601 notation

        * start_display: Readably formatted start of the course

        * start_type: Hint describing how `start_display` is set. One of:

        * `"string"`: manually set by the course author

        * `"timestamp"`: generated from the `start` timestamp

        * `"empty"`: no start date is specified

        * pacing: Course pacing. Possible values: instructor, self

        * certificate_available_date (optional): Date the certificate will be available,

        in ISO 8601 notation if the `certificates.auto_certificate_generation`

        waffle switch is enabled


        Deprecated fields:


        * blocks_url: Used to fetch the course blocks

        * course_id: Course key (use ''id'' instead)


        **Parameters:**


        username (optional):

        The username of the specified user for whom the course data

        is being accessed. The username is not only required if the API is

        requested by an Anonymous user.


        **Returns**


        * 200 on success with above fields.

        * 400 if an invalid parameter was sent or the username was not provided

        for an authenticated request.

        * 403 if a user who does not have permission to masquerade as

        another user specifies a username other than their own.

        * 404 if the course is not available or cannot be seen.


        Example response:


        {

        "blocks_url": "/api/courses/v1/blocks/?course_id=edX%2Fexample%2F2012_Fall",

        "media": {

        "course_image": {

        "uri": "/c4x/edX/example/asset/just_a_test.jpg",

        "name": "Course Image"

        }

        },

        "description": "An example course.",

        "end": "2015-09-19T18:00:00Z",

        "enrollment_end": "2015-07-15T00:00:00Z",

        "enrollment_start": "2015-06-15T00:00:00Z",

        "course_id": "edX/example/2012_Fall",

        "name": "Example Course",

        "number": "example",

        "org": "edX",

        "overview: "

        A verbose description of the course.

        "

        "start": "2015-07-17T12:00:00Z",

        "start_display": "July 17, 2015",

        "start_type": "timestamp",

        "pacing": "instructor",

        "certificate_available_date": "2015-08-14T00:00:00Z"

        }'
      tags:
      - Courses
      parameters:
      - name: course_key_string
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourseDetail'
  /courses/v2/block_metadata/{usage_key_string}:
    get:
      operationId: courses_v2_block_metadata_read
      summary: '**Use Case**'
      description: 'Returns the block metadata. Data like index_dictionary related to a

        block should be fetched using this API, because they are too large for

        the cache used by the course blocks/transformers API.


        **Example requests**:


        GET /api/courses/v1/block_metadata//?

        &include=index_dictionary


        **Parameters**:


        * "include": a comma-separated list of keys to include.

        Valid keys are "index_dictionary".


        **Response Values**


        A dictionary containing:

        * id (string): Block usage_key_str.

        * type (string) Block type.

        * index_dictionary: (dict) The index_dictionary JSON data

        (usually this is the text content of the block, for search

        indexing or other purposes) for this block. Returned only if

        the "index_dictionary" is included in the "include"

        parameter.'
      tags:
      - Courses
      parameters:
      - name: usage_key_string
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
  /courses/v2/blocks/:
    get:
      operationId: courses_v2_blocks_list
      summary: '**Use Case**'
      description: 'Returns the blocks in the course according to the requesting user''s

        access level.


        **Example requests**:


        GET /api/courses/v1/blocks/?course_id=

        GET /api/courses/v1/blocks/?course_id=

        &username=anjali

        &depth=all

        &requested_fields=graded,format,student_view_multi_device,lti_url

        &block_counts=video

        &student_view_data=video

        &block_types_filter=problem,html


        **Parameters**:


        This view redirects to /api/courses/v1/blocks// for the

        root usage key of the course specified by course_id. The view accepts

        all parameters accepted by :class:`BlocksView`, plus the following

        required parameter


        * course_id: (string, required) The ID of the course whose block data

        we want to return


        **Response Values**


        Responses are identical to those returned by :class:`BlocksView` when

        passed the root_usage_key of the requested course.


        If the course_id is not supplied, a 400: Bad Request is returned, with

        a message indicating that course_id is required.


        If an invalid course_id is supplied, a 400: Bad Request is returned,

        with a message indicating that the course_id is not valid.'
      tags:
      - Courses
      parameters:
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
  /courses/v2/blocks/{usage_key_string}:
    get:
      operationId: courses_v2_blocks_read
      summary: '**Use Case**'
      description: 'Returns the blocks within the requested block tree according to the

        requesting user''s access level.'
      tags:
      - Courses
      parameters:
      - name: usage_key_string
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
      responses:
        '200':
          description: ''
components:
  schemas:
    CourseDetail:
      required:
      - effort
      - end
      - enrollment_start
      - enrollment_end
      - id
      - media
      - name
      - number
      - org
      - short_description
      - start
      - start_display
      - start_type
      - pacing
      - mobile_available
      - invitation_only
      type: object
      properties:
        blocks_url:
          title: Blocks url
          type: string
          readOnly: true
        effort:
          title: Effort
          type: string
          minLength: 1
        end:
          title: End
          type: string
          format: date-time
        enrollment_start:
          title: Enrollment start
          type: string
          format: date-time
        enrollment_end:
          title: Enrollment end
          type: string
          format: date-time
        id:
          title: Id
          type: string
          minLength: 1
        media:
          $ref: '#/components/schemas/_CourseApiMediaCollection'
        name:
          title: Name
          type: string
          minLength: 1
        number:
          title: Number
          type: string
          minLength: 1
        org:
          title: Org
          type: string
          minLength: 1
        short_description:
          title: Short description
          type: string
          minLength: 1
        start:
          title: Start
          type: string
          format: date-time
        start_display:
          title: Start display
          type: string
          minLength: 1
        start_type:
          title: Start type
          type: string
          minLength: 1
        pacing:
          title: Pacing
          type: string
          minLength: 1
        mobile_available:
          title: Mobile available
          type: boolean
        hidden:
          title: Hidden
          type: string
          readOnly: true
        invitation_only:
          title: Invitation only
          type: boolean
        course_id:
          title: Course id
          type: string
          readOnly: true
          minLength: 1
        overview:
          title: Overview
          type: string
          readOnly: true
    Image:
      required:
      - raw
      - small
      - large
      type: object
      properties:
        raw:
          title: Raw
          type: string
          format: uri
          minLength: 1
        small:
          title: Small
          type: string
          format: uri
          minLength: 1
        large:
          title: Large
          type: string
          format: uri
          minLength: 1
    Course:
      required:
      - effort
      - end
      - enrollment_start
      - enrollment_end
      - id
      - media
      - name
      - number
      - org
      - short_description
      - start
      - start_display
      - start_type
      - pacing
      - mobile_available
      - invitation_only
      type: object
      properties:
        blocks_url:
          title: Blocks url
          type: string
          readOnly: true
        effort:
          title: Effort
          type: string
          minLength: 1
        end:
          title: End
          type: string
          format: date-time
        enrollment_start:
          title: Enrollment start
          type: string
          format: date-time
        enrollment_end:
          title: Enrollment end
          type: string
          format: date-time
        id:
          title: Id
          type: string
          minLength: 1
        media:
          $ref: '#/components/schemas/_CourseApiMediaCollection'
        name:
          title: Name
          type: string
          minLength: 1
        number:
          title: Number
          type: string
          minLength: 1
        org:
          title: Org
          type: string
          minLength: 1
        short_description:
          title: Short description
          type: string
          minLength: 1
        start:
          title: Start
          type: string
          format: date-time
        start_display:
          title: Start display
          type: string
          minLength: 1
        start_type:
          title: Start type
          type: string
          minLength: 1
        pacing:
          title: Pacing
          type: string
          minLength: 1
        mobile_available:
          title: Mobile available
          type: boolean
        hidden:
          title: Hidden
          type: string
          readOnly: true
        invitation_only:
          title: Invitation only
          type: boolean
        course_id:
          title: Course id
          type: string
          readOnly: true
          minLength: 1
    _AbsolutMedia:
      type: object
      properties:
        uri:
          title: Uri
          type: string
          readOnly: true
        uri_absolute:
          title: Uri absolute
          type: string
          readOnly: true
    _CourseApiMediaCollection:
      required:
      - banner_image
      - course_image
      - course_video
      - image
      type: object
      properties:
        banner_image:
          $ref: '#/components/schemas/_AbsolutMedia'
        course_image:
          $ref: '#/components/schemas/_Media'
        course_video:
          $ref: '#/components/schemas/_Media'
        image:
          $ref: '#/components/schemas/Image'
    _Media:
      type: object
      properties:
        uri:
          title: Uri
          type: string
          readOnly: true
  securitySchemes:
    Basic:
      type: http
      scheme: basic