Взаимодействия

Вызов методов

Для вызова любого метода API необходимо отправить POST запрос по протоколу HTTPS на указанный адрес

Передача параметров

Передача параметров может осуществляется как через POST-форму или GET-параметры запроса, так и через тело запроса в виде JSON.

Обработка ответа

Каждый запрос в API возвращает ответ сериализованный в формате JSON.

Ответ является стандартизированным и может содержать один из объектов

• response - доступен, в случае успешного ответа
• update - доступен только вместе с response, содержит обновленные данные объекта
• error - доступен, в случае возникновения ошибки при выполнении запроса

Примеры успешного ответа

// Ответ содержит информацию об одном объекте
{
    "response": {
        "id":         1,
        "first_name": "Developer Test",
        "is_admin":   1,
    }
}

// Ответ содержит информацию со списком объектов
// count - общее количество доступных для выборки объектов
// items - список выбранных объектов с учетом переданных фильтров
{
    "response": {
        "count": 10,
        "items": [
            ...
        ],
    },
    "update": {
        "member": {
            ...
        }
    }
}

// Ответ содержит результат выполнения запроса и обновленные данные объекта
{
    "response": {
        "success":   1,
        "timestamp": 1491279174.7654
    },
    "update": {
        "member": {
            ...
        }
    }
}

Пример ошибки

{
    "error": {
        "code":      10002,
        "text":      "Invalid parameter `site_id`",
        "error_id":  990,
        "timestamp": 1597852096.013394,
        "name":      "site_id"
    }
}

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

В случае возникновения ошибки будет возвращен объект error, содержащий поля

Список ошибок

Как реагировать

API подразумевает три исхода выполнения запроса: ошибка, успешное выполнение, неуспешное выполнение.

Ошибка

Ошибка возникает в том случае, когда в вызов метода были переданные неверные параметры или объект, который необходимо изменить не может быть изменен, потому что имеет определенный статус в системе или не принадлежит текущему пользователю.

Пример

{
    "error": {
        "code":      10002,
        "text":      "Invalid parameter `item_id`",
        "error_id":  990,
        "timestamp": 1597852096.013394,
        "name":      "item_id"
    }
}

Успешное выполнение

Успешное выполнение подразумевает, что метод был вызван без ошибок и операция была проведена успешно.

Пример

{
    "response": {
        "success":   1,
        "timestamp": 1491279174.7654
    }
}

Неуспешное выполнение

Неуспешное выполнение возникает в том случае, когда метод был вызван без ошибок, но при вызове ничего не изменилось. В данном случае система дополнительно вернет в ответе поле reason, которое будет содержать описание ошибки. Так же ответ может содержать дополнительные служебные поля.

Пример

{
    "response": {
        "success":   0,
        "timestamp": 1491279174.7654,
        "reason":    "Усиление уже запущено",
        "expires":   1491279974,
    }
}