Общие сведения

Структура API

API служит для вызова функций сервиса SeoBrain программным способом. Это необходимо для интеграции сторонних информационных систем с возможностями сервиса.

Все запросы к API следует отправлять на http://api.seobrain.ru/{версия API}/

API построен по REST принципам. Всё, чем можно управлять через API, является ресурсами: проекты, запросы, позиции.

Ресурс – это некая целостная часть системы, с которой можно работать. Каждый ресурс имеет свой уникальный URL.
Все операции с ресурсом выполняются соответствующими методами протокола HTTP на URL ресурса.

HTTP метод Тип действия
GET читать содержимое ресурса
POST операции по изменению ресурса: добавление, удаление, редактирование.
сопровождается параметром action

Для правильного распознавания ваших запросов к API их содержимое должно быть в кодировке UTF-8

Все ответы API отдает в формате JSON в кодировке UTF-8.

Авторизация

Все запросы к API должны содержать авторизационный токен в HTTP заголовке Authorization или передаваться как часть запроса в параметре apiKey.

Авторизационный токен можно получить самостоятельно в личном кабинете.

Обработка ошибок

По умолчанию сервис всегда отдает HTTP статус 200.

Если необходимо получать HTTP код соответствующий ошибке, в параметрах запроса необходимо передать параметр:

suppress_response_code = false

Если запрос к API выполнен с ошибкой, ответ содержит поле code с кодом и описанием ошибки в поле error.

Приложения

Коды состояния HTTP

Код Описание Комментарии
200 OK Запрос на получение данных (GET) завершен успешно. Тело ответа содержит запрошенные данные.
400 Bad Request Запрос содержит неверные данные: неверный формат параметр или отсутствие обязательных В теле ответа код и описание ошибки
401 Unauthorized Требуется авторизация см. Авторизация
403 Forbidden Доступ к API временно заблокирован Например, из-за слишком частых запросов
404 Not Found Ресурс не найден. В теле ответа код и описание ошибки
405 Method Not Allowed Метод протокола HTTP для ресурса не разрешен.
5XX Неизвестная ошибка. Вероятно, проводятся плановые работы. Повторите запрос позже.

Коды ошибок

Код Описание
1 Системная ошибка. Сопровождается кодом состояния HTTP 500
2 Неверный apiKey
6 Проекта с таким id не существует или он не соответствует apiKey
7 Региона с указанным id не существует
9 Неверный формат параметров

Версии API

Версия Описание API Дата релиза Комментарии
v1 Описание 20.01.2014 Основные методы получения информации о проектах сервиса SeoBrain
v1_1 Описание 31.07.2015 Изменена струкутра ответа на запрос получения позиций по проекту