kneu-api-client v1.0.2
JS client for KNEU RESTful API Service
This JS Library provide programmatic user-friendly interface to work with the KNEU RESTful API and OAuth 2.0.
JS-бібліотека забезпечує зручний програмний інтерфейс для роботи з КНЕУ RESTful API та протоколом OAuth 2.0. Бібліотека розрахована на роботу в браузері. Для роботи бібліотеки потрібно отримати client_id, client_secret, а також повідомити перелік доменних імен пов'язаних з вашим додатком. Доступ до API можливий лише з визначеного дозволенного переліку доменних імен.
Встановлення
Додати бібліотеку до Вашого проекту за допомогою NPM або завантажити вихідний код пакету
npm install kneu-api-client
підключити бібліотеку до Вашого веб-проекту
<script src="./kneuApiClient.js"></script>
Ініціалізація
Для ініціалізації бібліотеки потрібен AccessToken, який був отрманний сервером через процедуру Авторизації сервера
let api = new KneuApi('{ACCESS_TOKEN}');
У випадку використання разом з РНР Бібліотекою, підключення може бути реалізовано у наступному порядку:
<?php
api = Kneu\Api::createWithServerToken(client_id, client_secret);
?>
<script src="./kneuApiClient.js"></script>
<script>
let api = new KneuApi('<?= await api.getAccessToken() ?>');
</script>
Опис методів
getFaculties([object filters = {},] [[number offset = null,] number limit = null]): Promise<object[]>
Отримати перелік факультетів
await api.getFaculties();
await api.getFaculties(limit);
await api.getFaculties(offset, limit);
let facultiesListExample =
[
{
"id": 1,
"name": "Економіки та управління"
},
...
]
getDepartments([object filters = {},] [[number offset = null,] number limit = null]): Promise<object[]>
Отримати перелік кафедр Дозволяє отримати перелік кафедр. Надає перелік:
- всіх кафедр відсортованних за id.
- кафедр вибраного факультету
faculty_id
відсортованних за назвою.
Об'єкт Кафедра надається разом з даними по зв'язанному об'єкту Факультет.
await api.getDepartments(); // all
await api.getDepartments({faculty_id: 999}); // by faculty id
await api.getDepartments(filters);
await api.getDepartments(filters, limit);
await api.getDepartments(filters, offset, limit);
await api.getDepartments(offset, limit);
await api.getDepartments(limit);
let departmentsListExample =
[
{
"id": 53,
"faculty_id": 3,
"name": "Адміністративного та фінансового права",
"faculty": {
"id": 3,
"name": "Юридичний інститут"
}
},
{
"id": 57,
"faculty_id": 3,
"name": "Іноземних мов юридичного інституту",
"faculty": {
"id": 3,
"name": "Юридичний інститут"
}
},
...
]
getTeachers([object filters = {},] [[number offset = null,] number limit = null]): Promise<object[]>
Дозволяє отримати перелік викладачів. Надає перелік:
- всіх викладачів відсортаванних за id.
- викладачів певного факультету
faculty_id
або кафедриdepartment_id
в алфавітному порядку за прізвищем. Об'єкт викладач надається разом даними зв'язаних об'єктів Кафедра та Користувач (User).
Увага! Обєкт User є необов'язковий. Присутний лише в разі, коли викладач вже зар'єструвався на сайті.
Внутрішня реалізація метода автоматично робить потрібну кількисть запитів до сервера, щоб отримати повний список викладачів.
await api.getTeachers(); // all teachers
await api.getTeachers({faculty_id: 999}); // by faculty
await api.getTeachers({department_id: 999}); // by department
await api.getTeachers(filters);
await api.getTeachers(filters, limit);
await api.getTeachers(filters, offset, limit);
await api.getTeachers(offset, limit);
await api.getTeachers(limit);
let teachersListExample =
[
{
"id": 1105,
"department_id": 21,
"name": "Іваненко Іван Іванович",
"first_name": "Іван",
"middle_name": "Іванович",
"last_name": "Іваненко",
"image_url": "https:\/\/kneu.edu.ua\/files\/teacher\/teacher_photo\/thumbnail_1113333.jpg",
"user": {
"id": 5019,
"login": "example@gmail.com"
},
"department": {
"id": 21,
"faculty_id": 3,
"name": "Цивільного та трудового права"
}
},
...
]
getSpecialties([object filters = {},] [[number offset = null,] number limit = null]): Promise<object[]>
Дозволяє отримати перелік спеціальностей. Надає перелік:
- всіх спеціальностей сортованних за id
- спеціальностей певного факультету
faculty_id
сортованних за назвою.
Надається разом із даними зв'язаного об'єкту Факультет. Внутрішня реалізація метода автоматично робить потрібну кількисть запитів до сервера, щоб отримати повний список спеціальностей.
await api.getSpecialties(); // all specialties
await api.getSpecialties({faculty_id: 999}); // by faculty
await api.getSpecialties(filters);
await api.getSpecialties(filters, limit);
await api.getSpecialties(filters, offset, limit);
await api.getSpecialties(offset, limit);
await api.getSpecialties(limit);
let specialtiesListExample =
[
{
"id": 131,
"faculty_id": 9,
"code": "6701",
"name": "Безпепека інформаційних і комунікаційних систем",
"faculty": {
"id": 9,
"name": "Інститут інформаційних технологій в економіці"
}
},
{
"id": 173,
"faculty_id": 9,
"code": "6.051",
"name": "Економіка",
"faculty": {
"id": 9,
"name": "Інститут інформаційних технологій в економіці"
}
},
...
]
getGroups([object filters = {},] [[number offset = null,] number limit = null]): Promise<object[]>
Дозволяє отримати перелік академічних груп. Надає перелік:
- всіх академічних груп відсортованних за id;
- академичніних груп певної спеціальності
specialty_id
або факультетуfaculty_id
відсортованних за назвою спеціальності та назвою групи
Об'єкт група надається разом із зв'заним об'єктом спеціальність.
await api.getGroups(); // all groups
await api.getGroups({faculty_id: 999}); // by faculty
await api.getGroups({specialty_id: 999}); // by specialty
await api.getGroups(filters);
await api.getGroups(filters, limit);
await api.getGroups(filters, offset, limit);
await api.getGroups(offset, limit);
await api.getGroups(limit);
let groupsListExample =
[
{
"id": 13293,
"specialty_id": 33,
"course": 2,
"name": "ПР.-201",
"specialty": {
"id": 33,
"faculty_id": 18,
"code": "7.03040101",
"name": "Правознавство"
}
},
{
"id": 13297,
"specialty_id": 36,
"course": 2,
"name": "ОА.-201",
"specialty": {
"id": 36,
"faculty_id": 18,
"code": "7.03050901",
"name": "Облік і аудит"
}
},
...
]
getStudents([object filters = {},] [[number offset = null,] number limit = null]): Promise<object[]>
Дозволяє отримати перелік студентів. Надає перелік:
- всіх студентів, відсортованних за id
- студентів певної академічної групи
group_id
підсортованих в алфавітному порядку за прізвищем
Якщо студент зарєстрованний на сайті, додатково до додається інформацію про звязанну сутність користувач (User). Якщо студент не зарєстрованний на сайті - інформація про User відсутня у результаті. Внутрішня реалізація метода автоматично робить потрібну кількисть запитів до сервера, щоб отримати повний список груп.
await api.getStudents(); // all students
await api.getStudents({group_id: 999}); // by group and order by name
await api.getStudents(filters);
await api.getStudents(filters, limit);
await api.getStudents(filters, offset, limit);
await api.getStudents(offset, limit);
await api.getStudents(limit);
let studentsListExample =
[
{
"id": 444,
"group_id": 123,
"gradebook_id": "999999",
"sex": "male",
"name": "Іваненко Павло Володимирович",
"first_name": "Павло",
"middle_name": "Володимирович",
"last_name": "Іваненко",
"birthdate": "1992-07-13",
"user": {
"id": 32664,
"login": "example@gmail.com"
}
},
...
]
- Parameters:
- Returns:
array
- Throws:
Error
getFaculty(integer id): Promise<object>
Отримати факультет зі вказаним id
getDepartment(integer id): Promise<object>
Отримати кафедру зі вказаним id
getTeacher(integer id): Promise<object>
Отримати викладача зі вказаним id
getSpecialty(integer id): Promise<object>
Отримати спеціальність зі вказаним id
getGroup(integer id): Promise<object>
Отримати групу зі вказаним id
getStudent(integer id): Promise<object>
Отримати студента зі вказаним id
getContentRange(key)
Дозволяє отримати Meta-інформацію про загальну кількість об'єктів певної сутності (для переліку викладачів, спеціальностей, факультетів тощо).
Інформація надається із заголовку Content-Range, тому метод getContentRange()
може надати інформацію лише після виконання методу (запиту) на отримання переліку об'єктів певної сутності.
Наприклад, метод getContentRange()
доцільно викликати після виконання методів getTeachers()
, getGroups()
, getSpecialities()
тощо.
Детальніше застосування методу getContentRange()
подано в прикладі коду нижче (у розділі Авторизація серверу та імпорт бази даних).
- Parameters:
key
—string
— enum("total", "start", "end")- total - загальна кількість об'єктів (total count from database)
- start - початок зсуву даних починаючи під початку (від 0). Аналог SQL LIMIT start, 100. Іншими словам - індексу першого об'єкту з останнього запиту в загальному переліку об'єктів.
- end - кінець зсуву даних. end = start + limit - 1 за аналогією з SQL LIMIT start, limit. Іншими словам - індексу останнього об'єкту з останнього запиту в загальному переліку об'єктів.
- Якщо значення
key
не задано, то метод поверне масив з ключами start, end, total.
- Returns:
array|integer|null
Приклад використання
Авторизація серверу та імпорт даних
let api = new KneuApi('{ACCESS_TOKEN}');
try {
for (let teacher of await api.getTeachers()) {
console.log(teacher);
}
for (let teacher of await api.getTeachers({department_id: 21})) {
console.log(teacher);
}
for (let teacher of await api.getTeachers({faculty_id: 3})) {
console.log(teacher);
}
for (let department of await api.getDepartments({faculty_id: 3})) {
console.log(department);
}
for (let student of await api.getStudents({group_id: 17867})) {
console.log(student);
}
} catch (e) {
console.log(e);
}
async/await
Всі методи классу KneuApi
є асинхроними. Виклакати їх потрібно:
1) В асинхроних функціях з ключовими словом await
document.addEventListener("DOMContentLoaded", async function() {
try {
let departments = await api.getDepartments({faculty_id: 3});
for (let department of departments) {
console.log(department);
}
} catch (e) {
console.log(e);
}
});
2) В синхроних (звичайних) функціях методи повертають об'єкт Promise.
api.getDepartments({faculty_id: 3}).then(function (departments) {
for (let department of departments) {
console.log(department);
}
}, function (e) {
console.log(e);
});
Детальніше про JS acync/await