API 2.0

API расширяет возможности использования системы. С помощью API компании "Клиентская База" можно подключить свой телеграм бот, настроить телефонию, сделать интеграцию с сайтом и многое другое.

Форматы запросов и ответов к API имеют кодировку UTF-8, соответствуют спецификации JSON и используют REST-архитектуру.

Методы

API включает следующие методы (в фигурных скобках находятся изменяемые значения):

• /dev/api/data{ID-таблицы} — работа с пользовательской таблицей
  • GET - получить список записей пользовательской таблицы
  • POST - создать запись в пользовательской таблице
• /dev/api/data{ID-таблицы}/{ID-записи} — работа с записью пользовательской таблицы
  • GET - получить данные указанной записи
  • PATCH - обновить данные указанной записи
  • DELETE - удалить указанную записи
• /dev/api/table — список таблиц
  • GET - получить список таблиц с данными структуры и прав доступа
• /dev/api/table{ID-таблицы} — информация о структуре таблицы и правах доступа к ней
  • GET - получить данные структуры и прав доступа к указанной таблице
• /dev/api/user — список пользователей
  • GET — получить список пользователей
• /dev/api/user{ID-пользователя} — информация о пользователе
  • GET — получить информацию о указанном пользователе
• /dev/api/group — список групп пользователей
  • GET — получить список групп пользователе
• /dev/api/group{ID-группы} — информация о группе пользователей
  • GET — получить информацию о указанной группе пользователей
• /dev/api/file/{ID-таблицы}/{ID-поля}/{ID-записи}/?filename={название файла} — информация о файле
  • GET — получить информацию о файле, хранящемся в указанном поле таблицы

Типы запросов

Методы используют типы запросов GET, POST и другие, которые имеют смысл в конкретном случае.
GET — Получить данные или список данных
POST — Добавить данные
PATCH — Изменить данные
DELETE — Удалить данные

Проверка работы API без аутентификации

Данный метод выводит приветствие с указанным текстом: "Hello, {Ваш-текст}!"

Запрос

GET {URL-аккаунта}/api/dev/hello/{Ваш-текст}

Замените {URL-аккаунта} на URL экземпляра КБ, например, https://demo.clientbase.ru или http://localhost:8080/.
Замените {Ваш-текст} на любой текст.

Формат ответа

200 OK (application/vnd.api+json)
либо ошибка

Аутентификация

Для работы с API необходим API-токен, который будет передаваться в заголовке запроса.
Для получения API-токена перейдите в раздел Настройки -> Еще -> Управление API-токенами (API 2.0), выберите пользователя, задайте дату окончания действия ключа и нажмите «Добавить».

Запросы выполняются с правами доступа пользователя, для которого создан токен. Рекомендуем выбрать пользователя из группы доступа «Администратор».

Готовая библиотека

Для удобной работы с API вы можете воспользоваться готовой библиотекой на PHP.

Коды HTTP-ответов частых ошибок

400 — некорректный запрос (неверные параметры или не прошла валидация)
401 — ошибка авторизации
403 — доступ запрещён по правам
404 — объект не найден
405 — метод не разрешён для использования
426 — необходима докупка лицензий (доступ к модулям не входящим в лицензию)
429 — превышено число допустимых запросов (лимит частоты запросов)
443 — нет прав доступа к объекту 500 — неизвестная ошибка сервера (не обработанное исключение в коде сервера)
501 — метод ресурса не существует или не реализован