Гайды
Как работать с эндпоинтами v200.1.0
База /api/v2: пропуск Bearer, sugar vs /table/, ответы и типичные ошибки.
API — это набор адресов на сайте вида https://ВАШ_САЙТ/api/v2/…. Этот гайд объясняет как думать про них. Полный список путей — в HTTP и OpenAPI.
Что нужно заранее
- Установка
- Авторизация — получить Bearer (
access_token) - При демо-проблемах — Инструкция .env
Два вида адресов
| Вид | Пример | Зачем |
|---|---|---|
| Sugar (короткий) | POST /post/, POST /user/, POST /plugin/ | Удобное создание одной сущности |
| Универсальный CRUD | /table/post/, /table/users/ | Список, чтение, правка, удаление любой разрешённой таблицы |
Sugar почти всегда только create. Список новостей — GET /post/ или GET /table/post/; обновить новость — PUT /table/post/{id}.
Права (можно ли читать/писать таблицу) задаёт уровень доступа ключа.
Некоторые служебные таблицы (api_keys, oauth_*, …) через /table/ закрыты.
Как выглядит запрос
curl -sS 'https://ВАШ_САЙТ/api/v2/table/users/?limit=20' \
-H 'Authorization: Bearer <access_token>'Слеш в конце необязателен.
Типичный ответ списка:
{
"data": [ … ],
"count": 42
}Создание часто отвечает 201 и { "id": 123 }.
Ошибки простыми словами
Большинство ошибок — JSON с полями error и message (схема ApiError в OpenAPI).
| Код | Обычно значит |
|---|---|
| 401 | Нет пропуска или он просрочен — auth |
| 403 | Токен есть, но нет scope на эту операцию — access-levels |
| 404 | Нет такой записи / таблицы |
| 422 | Тело запроса не прошло проверку (смотрите details) |
Куда идти дальше
| Задача | Гайд |
|---|---|
| Создать / искать новости | posts-create, posts-search |
| Доп. поля новости | xfields-news |
| Пользователи | users-create, users-search |
| Плагин | plugins-create |
| То же из PHP на сайте | SDK |
| Было v1 | migrate-v1-v2 |