Al-Farabi Kazakh National University Notifications API

openapi: 3.2.0
info:
  title: Open edX Notifications 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: Notifications
paths:
  /notifications/:
    get:
      operationId: notifications_list
      summary: API view for listing notifications for a user
      description: '**Permissions**: User must be authenticated.

        **Response Format** (paginated):


        {

        "results" : [

        {

        "id": (int) notification_id,

        "app_name": (str) app_name,

        "notification_type": (str) notification_type,

        "content": (str) content,

        "content_context": (dict) content_context,

        "content_url": (str) content_url,

        "last_read": (datetime) last_read,

        "last_seen": (datetime) last_seen

        },

        ...

        ],

        "count": (int) total_number_of_notifications,

        "next": (str) url_to_next_page_of_notifications,

        "previous": (str) url_to_previous_page_of_notifications,

        "page_size": (int) number_of_notifications_per_page,


        }


        Response Error Codes:

        - 403: The requester cannot access resource.'
      tags:
      - Notifications
      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/Notification'
  /notifications/configurations/:
    get:
      operationId: notifications_configurations_list
      description: API view for getting the aggregate notification preferences for the current user.
      tags:
      - Notifications
      responses:
        '200':
          description: ''
      summary: Notifications configurations list
      x-summary-source: derived
  /notifications/configurations/{course_key_string}:
    get:
      operationId: notifications_configurations_read
      summary: Returns notification preference for user for a course
      description: 'Parameters:

        request (Request): The request object.

        course_key_string (int): The ID of the course to retrieve notification preference.


        Returns:

        {

        ''id'': 1,

        ''course_name'': ''testcourse'',

        ''course_id'': ''course-v1:testorg+testcourse+testrun'',

        ''notification_preference_config'': {

        ''discussion'': {

        ''enabled'': False,

        ''core'': {

        ''info'': '''',

        ''web'': False,

        ''push'': False,

        ''email'': False,

        },

        ''notification_types'': {

        ''new_post'': {

        ''info'': '''',

        ''web'': False,

        ''push'': False,

        ''email'': False,

        },

        },

        ''not_editable'': {},

        },

        }

        }'
      tags:
      - Notifications
      parameters:
      - name: course_key_string
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
    patch:
      operationId: notifications_configurations_partial_update
      description: Update an existing user notification preference with the data in the request body.
      tags:
      - Notifications
      parameters:
      - name: course_key_string
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
      summary: Notifications configurations partial update
      x-summary-source: derived
  /notifications/count/:
    get:
      operationId: notifications_count_list
      summary: Get the unseen notifications count and show_notification_tray flag for a user
      description: '**Permissions**: User must be authenticated.

        **Response Format**:

        ```json

        {

        "show_notifications_tray": (bool) show_notifications_tray,

        "count": (int) total_number_of_unseen_notifications,

        "count_by_app_name": {

        (str) app_name: (int) number_of_unseen_notifications,

        ...

        },

        "notification_expiry_days": 60

        }

        ```

        **Response Error Codes**:

        - 403: The requester cannot access resource.'
      tags:
      - Notifications
      responses:
        '200':
          description: ''
  /notifications/enrollments/:
    get:
      operationId: notifications_enrollments_list
      summary: API endpoint to get active CourseEnrollments for requester
      description: '**Permissions**: User must be authenticated.

        **Response Format** (paginated):


        {

        "next": (str) url_to_next_page_of_courses,

        "previous": (str) url_to_previous_page_of_courses,

        "count": (int) total_number_of_courses,

        "num_pages": (int) total_number_of_pages,

        "current_page": (int) current_page_number,

        "start": (int) index_of_first_course_on_page,

        "results" : [

        {

        "course": {

        "id": (int) course_id,

        "display_name": (str) course_display_name

        },

        },

        ...

        ],

        }


        Response Error Codes:

        - 403: The requester cannot access resource.'
      tags:
      - Notifications
      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/NotificationCourseEnrollment'
  /notifications/mark-seen/{app_name}/:
    put:
      operationId: notifications_mark-seen_update
      description: API view for marking user's all notifications seen for a provided app_name.
      tags:
      - Notifications
      parameters:
      - name: app_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
      summary: Notifications mark seen update
      x-summary-source: derived
    patch:
      operationId: notifications_mark-seen_partial_update
      description: API view for marking user's all notifications seen for a provided app_name.
      tags:
      - Notifications
      parameters:
      - name: app_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
      summary: Notifications mark seen partial update
      x-summary-source: derived
  /notifications/preferences/update-all/:
    post:
      operationId: notifications_preferences_update-all_create
      description: Update all notification preferences for the current user.
      tags:
      - Notifications
      responses:
        '201':
          description: ''
      summary: Notifications preferences update all create
      x-summary-source: derived
  /notifications/preferences/update/{username}/{patch}/:
    get:
      operationId: notifications_preferences_update_read
      description: 'View to update user preferences from encrypted username and patch.

        username and patch must be string'
      tags:
      - Notifications
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: patch
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
      summary: Notifications preferences update read
      x-summary-source: derived
    post:
      operationId: notifications_preferences_update_create
      description: 'View to update user preferences from encrypted username and patch.

        username and patch must be string'
      tags:
      - Notifications
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: patch
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: ''
      summary: Notifications preferences update create
      x-summary-source: derived
  /notifications/read/:
    patch:
      operationId: notifications_read_partial_update
      description: 'Marks all notifications or single notification read for the given

        app name or notification id for the authenticated user.'
      tags:
      - Notifications
      responses:
        '200':
          description: ''
      summary: Notifications read partial update
      x-summary-source: derived
components:
  schemas:
    CourseOverview:
      required:
      - id
      type: object
      properties:
        id:
          title: Id
          type: string
          maxLength: 255
          minLength: 1
        display_name:
          title: Display name
          type:
          - string
          - 'null'
          minLength: 1
    NotificationCourseEnrollment:
      required:
      - course
      type: object
      properties:
        course:
          $ref: '#/components/schemas/CourseOverview'
    Notification:
      required:
      - app_name
      - notification_type
      type: object
      properties:
        id:
          title: ID
          type: integer
          readOnly: true
        app_name:
          title: App name
          type: string
          maxLength: 64
          minLength: 1
        notification_type:
          title: Notification type
          type: string
          maxLength: 64
          minLength: 1
        content_context:
          title: Content context
          type: object
        content:
          title: Content
          type: string
          readOnly: true
        content_url:
          title: Content url
          type:
          - string
          - 'null'
          format: uri
          maxLength: 200
        course_id:
          title: Course id
          type:
          - string
          - 'null'
          maxLength: 255
        last_read:
          title: Last read
          type:
          - string
          - 'null'
          format: date-time
        last_seen:
          title: Last seen
          type:
          - string
          - 'null'
          format: date-time
        created:
          title: Создано
          type: string
          format: date-time
          readOnly: true
  securitySchemes:
    Basic:
      type: http
      scheme: basic