Добавление информации о заданиях и изменениях в расписании напрямую через ручное редактирование файлов и таблиц базы данных крайне неудобно и непрактично, т.к. заполнять информацию сможете только Вы, а вместе с возможностью заполнения для другого человека Вы даёте ему доступ к серверу, что может быть небезопасно без правильной настройки. Поэтому у бота присутствует API, позволяющий сделать заполнение возможным без полного доступа к серверу - достаточно иметь только логин и пароль, заданный Вами в процессе настройки, о котором пойдёт речь далее. Также API позволяет Вам использовать клиентское приложение, заметно упрощающее заполнение информации как для Вас лично, так и для других людей, которым Вы, возможно, захотите предоставить доступ для заполнения информации. Вы можете также создавать несколько пользователей API, чтобы, в случае необходимости, иметь возможность аннулировать чей-то доступ к заполнению информации, не изменяя собственный пароль.

Как происходит взаимодействие с API?

Для того, чтобы выполнить любой метод API, ему необходимо передать HTTP-заголовок key, содержащий определённый ключ доступа. Ключ доступа действителен в течение 30 минут с момента последнего использования. Каждый ключ доступа привязан к конкретному IP адресу и имени пользователя из специальной таблицы базы данных. Если ключ был использован клиентом, имеющим IP-адрес, отличающийся от IP адреса клиента, создавшего ключ, то доступ к API не будет предоставлен, вместо этого будет выведена ошибка с кодом 4 ("Key is invalid for this IP address"). Пользователи также разделены по уровню привилегий на 2 группы, имеющие соответствующее значение в столбце pr_level таблицы пользователей в базе:

• 1 - обычный пользователь, может использовать почти все методы, но не может изменять список предметов и добавлять/удалять пользователей.
• 2 - пользователь с повышенными привилегиями, может использовать все методы API Получение ключа доступа происходит посредством обращения к скрипту api/auth.php (полный адрес будет выглядеть как https://your.domain/path/to/bot/ api/auth.php . В данной статье часть, не выделенная жирным шрифтом, указываться не будет).

Необходимо делать POST-запрос к данному скрипту с заголовком Content-Type: application/x-www-form-urlencoded и содержимым вида

user=username
pass=password

Вместо username и password имя пользователя и пароль соответственно.

Если логин и пароль верны, то будет отправлен json-объект, содержащий ключ, имя пользователя и pr_level этого пользователя в соответствующих полях. В противном случае будет возвращена ошибка.

В случае повторного обращения к скрипту api/auth.php, если в таблице базы данных уже присутствует действующий ключ для данного пользователя и ip адреса, и пароль введён верно, будет возвращён тот же ключ, и его действие будет продлено.

Методы API

Все методы данного API можно разделить на две группы:

• get-методы
• update-методы

Методы первой группы необходимы для получения уже записанной информации. Они вызываются при помощи GET-запроса и имеют небольшое число параметров, если вообще их имеют. В результате работы они возвращают определённый JSON-объект, содержащий необходимые сведения или информацию об ошибке, если где-то произошёл сбой. К этим методам относятся следующие:

• api/getSubjects.php - получить список предметов и их ID
• api/getHomework.php - получить информацию о задании по конкретному предмету
• api/getTimetable.php - получить информацию о расписании на все 6 учебных дней в текстовом и числовом виде
• api/getChanges.php - получить информацию об изменениях в расписании

Методы второй группы необходимы непосредственно для обновления информации, используемой ботом. Эти методы вызываются при помощи POST-запроса с заголовком Content-Type: application/json. В теле запроса должен быть, соответственно, json-объект, соответствующий определённой схеме. К этим методам относятся:

• api/updateHomework.php - обновить информацию о задании по конкретному предмету
• api/updateTimetable.php - обновить расписание
• api/updateChanges.php - обновить изменения в расписании

Следующие методы можно отнести в отдельную группу, но в целом они схожи с update-методами. Единственное отличие - пользователь, с данными которого создавался ключ доступа, должен иметь значение pr_level = 2. Вот эти методы:

• api/addSubjects.php - добавление предметов
• api/deleteSubjects.php - удаление предметов
• api/addUser.php - добавление пользователя
• api/deleteUser.php - удаление пользователя

Методы API

api/getSubjects.php

Метод для получения списка предметов и их ID.

Параметры:

Отсутствуют

Результат выполнения:

Если не возникло ошибок, то результатом будет JSON-объект, определяемый схемой:

{
    type':'array',
    'items':
    {
        'type':'object',
        'properties':
        {
            'ID':
            {
                'type':'integer',
                'required':true
            },
            'Name':
            {
                'type':'string',
                'required':true
            },
            'additionalProperties':false
        }
    }
}

api/getHomework.php

Метод для получения задания по одному конкретному предмету, определяемому по ID этого предмета.

Параметры:

• id - ID предмета

Результат выполнения:

Если не возникло ошибок, то результатом будет JSON-объект, определяемый схемой:

{
    'type':'object',
    'properties':{
        'ID':{
            'type':'integer', 
            'required':true
        },
        'Homework':{
            'type':'string', 
            'required':true
        }
    }
}

api/getTimetable.php

Метод для получения расписания на всю неделю в числовом и текстовом виде.

Параметры:

Отсутствуют

Результат выполнения:

Если не возникло ошибок, то результатом будет JSON-объект, определяемый схемой:

{
    'type':'object',
    'properties':{
        'NumericTimetable':{
            'type': 'array',
            'items':{
                'type':'array',
                'items':{
                    'type':'integer'
                }
            },
            'required':true
        },
        'TextTimetable':{
            'type':'array',
            'items':{
                'type':'string'
            }, 
            'required':true
        }
    }
}

api/getChanges.php

Метод для получения изменений в расписании.

Параметры:

Отсутствуют

Результат выполнения:

Если не возникло ошибок, то результатом будет JSON-объект, определяемый схемой:

{
    'type':'object',
    'properties':{
        'TextChanges':{
            'type':'string',
            'required':true
        },
        'NumericChanges':{
            'type':'array', 
            'items':{
                'type':'integer'
            }, 
            'required':true
        }
    }
}

api/updateHomework.php

Метод для обновления домашнего задания по конкретному предмету, определяемому по ID.

Тело запроса:

В теле запроса должен быть JSON-объект, описываемый схемой:

{
    'type':'object',
    'properties':{
        'ID':{
            'type':'integer', 
            'required':true
        },
        'Homework':{
            'type':'string', 
            'required':true
        }
    }
}

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"updated":true}

api/updateTimetable.php

Метод для обновления расписания.

Тело запроса:

В теле запроса должен быть JSON-объект, описываемый схемой:

{
    'type':'object',
    'properties':{
        'NumericTimetable':{
            'type': 'array',
            'items':{
                'type':'array',
                'items':{
                    'type':'integer'
                }
            },
            'required':true
        },
        'TextTimetable':{
            'type':'array',
            'items':{
                'type':'string'
            }, 
            'required':true
        }
    }
}

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"updated":true}

Возможен вариант, когда будет возвращён результат false. Такого не должно происходить, но теоретически - это возможно. Если такое вдруг произойдёт - советую написать issue с описанием Ваших действий.

api/updateChanges.php

Метод для обновления изменений в расписании.

Тело запроса:

В теле запроса должен быть JSON-объект, описываемый схемой:

{
    'type':'object',
    'properties':{
        'TextChanges':{
            'type':'string',
            'required':true
        },
        'NumericChanges':{
            'type':'array', 
            'items':{
                'type':'integer'
            }, 
            'required':true
        }
    }
}

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"updated":true}

Возможен вариант, когда будет возвращён результат false. Такого не должно происходить, но теоретически - это возможно. Если такое вдруг произойдёт - советую написать issue с описанием Ваших действий.

api/addSubjects.php

Метод для добавления предметов в таблицу базы данных. Может быть выполнен только с ключом доступа пользователя, имеющего pr_level = 2

Тело запроса:

В теле запроса должен быть JSON-объект, описываемый схемой:

{
    'type':'object',
    'properties':{
        'names':{
            'type':'array', 
            'items':{
                'type':'string',
                "pattern":"^[\\\\wА-Яа-яЁё\\\\s-]{1,50}$"
            }, 
            'required':true
        }
    }
}

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"added_subjects":1}

Вместо 1 здесь число добавленных предметов. Если по каким-то причинам их добавится меньше, чем запланировано, то это можно будет сразу увидеть, сравнив количество предметов в запросе и количество, написанное в выводе.

api/deleteSubjects.php

Метод для удаления предметов из таблицы базы данных по их ID. Может быть выполнен только с ключом доступа пользователя, имеющего pr_level = 2

Тело запроса:

В теле запроса должен быть JSON-объект, описываемый схемой:

{
    'type':'object',
    'properties':{
        'IDs':{
            'type':'array', 
            'items':{
                'type':'integer'
            }, 
            'required':true
        }
    }
}

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"deleted_subjects":1}

Вместо 1 здесь число удалённых предметов. Если по каким-то причинам их было удалено меньше, чем запланировано, то это можно будет сразу увидеть, сравнив количество предметов в запросе и количество, написанное в выводе.

api/addUser.php

Метод для добавления нового пользователя в базу данных. Может быть выполнен только с ключом доступа пользователя, имеющего pr_level = 2

Тело запроса

В теле запроса должен быть JSON-объект, описываемый схемой:

{
    'type': 'object',
    'properties': {
        'user': {
            'type': 'string',
            'pattern': '^[\\\\w]+$',
            'required': true
        },
        'pass': {
            'type': 'string',
            'required': true
        },
        'pr': {
            'type': 'int',
            'minimum': 1,
            'maximum': 2
            'required': true
        }
    }
}

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"added":true}

api/deleteUser.php

Метод для удаления пользователя из базы данных. В случае попытки удалить пользователя, от имени которого выполняется запрос, будет выдана ошибка с кодом 7. Метод получает параметры через GET-запрос, т.е. параметры необходимо передавать в URL.

Может быть выполнен только с ключом доступа пользователя, имеющего pr_level = 2

Параметры:

• user - имя пользователя, которого надо удалить

Результат выполнения:

В случае успешного выполнения ответ сервера будет выглядеть следующим образом:

{"deleted":true}

Коды ошибок

Внутренние серверные ошибки

Данные ошибки возникают, если ошибка произошла внутри метода независимо от ввода пользователя, например, если не удалось подключиться к базе данных.

• Ошибка 1 - Ошибка соединения с базой данных
• Ошибка 2 - Ошибка выполнения запроса к базе данных
• Ошибка 8 - Невозможно произвести запись в файл.

Ошибки авторизации

• Ошибка 3 - Неверный логин или пароль
• Ошибка 4 - Неверный ключ доступа или ip адрес не соответствует изначальному ip-адресу
• Ошибка 5 - Срок действия ключа доступа истёк
• Ошибка 6 - Отсутствуют необходимые для авторизации параметры
• Ошибка 9 - Недостаточно прав для выполнения запроса

Ошибки запросов

• Ошибка 7 - Неправильный список параметров для метода