Документация API TheFrontend
Простая инструкция для работы с API: сначала откройте готовую ссылку, потом попробуйте fetch-запрос, а затем создавайте категории, посты и комментарии.
Base URL
https://front.bilimai.kg/api
Token
Это ваш ключ доступа. Добавляйте его в конец URL.
Format
API возвращает JSON: данные в формате для JavaScript.
Content-Type
application/json
Limit
До 100 записей на категорию сущности.
Для самых новичков
Что здесь происходит?
API - это ссылка, по которой ваш frontend получает или отправляет данные. Вы открываете URL или вызываете его через fetch, а сервер возвращает JSON.
API-ссылка
Обычная ссылка, например /api/personal. Она отдаёт данные.
Token
Ваш личный ключ. Без него API не поймёт, какие данные показать.
JSON
Формат данных для JavaScript. Похож на объект: {"status":"success"}.
Быстрый старт: первый запрос
Самый лёгкий способ проверить API - открыть ссылку в браузере. Если вы авторизованы и токен правильный, вы увидите JSON со списком клиентов.
https://front.bilimai.kg/api/personal?token=your_token
Скопируйте ссылку
Это готовый GET-запрос. Его можно открыть даже без кода.
Посмотрите JSON
JSON - это ответ сервера. Его потом читает ваш JavaScript.
Подключите fetch
Когда ссылка работает в браузере, вставьте её в пример с fetch.
Авторизация
Почти все API-ссылки требуют токен. Токен добавляется в конец URL после знака вопроса: ?token=your_token. Если токен неверный, API вернёт `401`.
https://front.bilimai.kg/api/category?token=your_token
Как читать методы
API-ссылки
Endpoint - это просто API-ссылка. В таблице показано, какой метод использовать, какой путь открыть и какие данные передать.
| Метод | Путь | Назначение | Что передать |
|---|---|---|---|
| GET | /api/personal | Список клиентов активного пользователя | token |
| GET | /api/category | Список категорий | token |
| GET | /api/category/parent | Дерево категорий | token |
| GET | /api/category/{id} | Одна категория с цепочкой родителей | token |
| POST | /api/category | Создать категорию | title, title_en, description, description_en, image |
| PUT | /api/category/{id} | Обновить категорию | Любое из редактируемых полей |
| PATCH | /api/category/{id} | Изменить статус категории | status: boolean |
| DELETE | /api/category/{id} | Удалить категорию без связанных постов | token |
| GET | /api/post | Список постов | token |
| GET | /api/post/{id} | Пост с лайками | token |
| GET | /api/post/comment/{id} | Пост с комментариями и лайками | token |
| POST | /api/post | Создать пост | title, title_en, description, description_en, image, image_en, category_id |
| PUT | /api/post/{id} | Обновить пост | Любое из редактируемых полей |
| PATCH | /api/post/{id} | Опубликовать или скрыть пост | is_published: boolean |
| DELETE | /api/post/{id} | Удалить пост, комментарии и лайки | token |
| GET | /api/comment | Дерево комментариев поста | post_id, token |
| POST | /api/comment | Создать комментарий | post_id, comment, comment_en |
Примеры запросов
Начните с первого примера. Он просто получает данные и выводит их в консоль браузера.
Самый простой fetch
Подходит для первого теста в JavaScript.
const response = await fetch("https://front.bilimai.kg/api/personal?token=your_token");
const data = await response.json();
console.log(data);Универсальная функция fetch
Используйте, когда будете делать GET, POST, PUT, PATCH и DELETE.
const API_BASE = "https://front.bilimai.kg/api";
const TOKEN = "your_token";
async function apiRequest(path, { method = "GET", body } = {}) {
const url = new URL(`${API_BASE}${path}`);
url.searchParams.set("token", TOKEN);
const response = await fetch(url, {
method,
headers: { "Content-Type": "application/json" },
body: body ? JSON.stringify(body) : undefined,
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.message || `HTTP ${response.status}`);
}
return data;
}Создать категорию
await apiRequest("/category", {
method: "POST",
body: {
title: "Новости",
title_en: "News",
description: "Раздел новостей",
description_en: "News section",
image: "https://example.com/category.jpg",
parent_id: null
}
});Изменить статус категории
await apiRequest("/category/12", {
method: "PATCH",
body: { status: false }
});Создать пост
await apiRequest("/post", {
method: "POST",
body: {
category_id: 12,
title: "Первый пост",
title_en: "First post",
description: "Короткое описание",
description_en: "Short description",
image: "https://example.com/post.jpg",
image_en: "https://example.com/post-en.jpg"
}
});Создать комментарий
await apiRequest("/comment", {
method: "POST",
body: {
post_id: 34,
comment: "Отличный материал",
comment_en: "Great article",
parent_id: null
}
});Поля и правила
Category
Обязательные при создании: `title`, `title_en`, `description`, `description_en`, `image`. `parent_id` необязателен и должен принадлежать этому же пользователю.
Post
Обязательные при создании: `category_id`, `title`, `title_en`, `description`, `description_en`, `image`, `image_en`. `client_id` можно передать при необходимости.
Comment
Обязательные при создании: `post_id`, `comment`, `comment_en`. Для ответа на другой комментарий передайте `parent_id`.
Статусы ответов
Частые ошибки новичков
?token=ваш_токен, и токен скопирован полностью.
title, title_en, description, description_en, image, image_en, category_id.
Content-Type: application/json.
Готовы попробовать API?
Зарегистрируйтесь, получите токен и начните собирать интерфейсы на реальных данных.