Администратору Vepp

Как работать с API Vepp

Общая информация


API URL

Для доступа к API используйте URL вида https://domain.com/api/service/api_version/function/

 Пояснения к URL

domain.com — публичный IP-адрес или домен сервера с Vepp. 

service — внутренний сервис для обработки запроса: auth. 

api_version — текущая версия API: v3.

function — функция для выполнения в Vepp.

Методы HTTP-запросов

Vepp поддерживает методы GET,  POST и DELETE.

Параметры POST-запроса

Чтобы передать параметры для POST-запроса, укажите их в теле запроса в формате JSON. 

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

Ответ на API-запросы приходит в виде JSON-объектов, например:

Сообщение об ошибке в JSON
{
  "error":
  {
    "code": <внутренний код ошибки, int>,
    "msg": <сообщение об ошибке, string>,
    "value": <дополнительная информация, object>
  }
}

Как обрабатывать код 503


Если Vepp длительное время неактивен, то он может быть приостановлен. В этом случае API-запросы завершаются с кодом 503. Повторяйте запросы, пока в ответ не будет получен другой код:

Пример реализации на Python 3
def retry(fn, **kwargs):
    response = fn(**kwargs)
    if response.status_code == 503:
        for attempt in range(1, 11):
            time.sleep(0.1 * attempt)
            logging.info(f'Try connect to {kwargs["url"]} number {attempt}')
            response = fn(**kwargs)
            if response.status_code != 503:
                break
    return response

def internal_post(url, data):
    headers = {"Host": "instance-" + os.environ["INSTANCE_ID"], "internal-auth": "on"}
    logging.info(f'Try connect to {url} with headers {headers}')
    retry(requests.post, url=url, json=data, headers=headers)

Способы авторизации


Доступность функций по API делится на 3 уровня: 

  • публичные функции — можно вызвать без авторизации;
  • функции пользователя — можно вызвать с уровнем доступа "Пользователь"; 
  • функции администратора — можно вызвать с уровнем доступа "Администратор". 

Для проверки текущего уровня доступа Vepp ищет в HTTP-заголовке cookie-файл с именем ses6. В нём должен содержаться код текущей сессии пользователя. Чтобы получить код сессии, используйте авторизацию по логину и паролю или по одноразовому ключу. 

Авторизация по логину и паролю

  1. Чтобы получить номер сессии, отправьте POST-запрос на URL вида https://domain.com/api/auth/v3/auth

    Тело запроса в JSON
    {
      "email": your_email,
      "password": your_password
    }
  2. Обработайте ответ. Он может содержать сообщение об ошибке, либо JSON вида: 

    Ответ в JSON
    {
      "expires_at": string,
      "id": int,
      "session": string
    }
  3. Используйте полученный номер сессии в заголовке HTTP-запроса, например:

    Использование в curl
    curl -k -H "Cookie:ses6=F2BABF12426B297C86FC5628" 'https://domain.com/api/auth/v3/user_exist/client@example.com'
  4. В случае ошибки будет получено сообщение вида: 

    Ошибка при авторизации
    {
      "error":
      {
        "code": 1114,
        "msg": "Whoami verifired error",
        "value":
        {
          "code": 3002,
          "msg": "Session not found"
        }
      }
    }

Сквозная авторизация по ключу

Vepp поддерживает сквозную авторизацию пользователя с использованием логина и пароля администратора. Например, её можно использовать для авторизованного перехода из биллинговой системы в Vepp. 

Алгоритм сквозной авторизации:

  1. С уровнем доступа "Администратор" отправьте POST-запрос для создания ключа: 

    Создать ключ для авторизации
    curl -X POST 'https://domain.com/api/auth/v3/user/client@example.com/key' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{}'| jq
  2. В ответ будет получен JSON-объект вида: 

    Ответ в JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "key": "94DA5B99AF0BF26D2E96458CABA8DA96"
    }
  3. Чтобы получить номер сессии, отправьте POST-запрос с полученным ключом: 

    Получить номер сессии по ключу
    curl -X POST 'https://domain.com/api/auth/v3/auth_by_key' -d '{"key": "94DA5B99AF0BF26D2E96458CABA8DA96"}'| jq
  4. В ответ будет получен JSON-объект вида: 

    Ответ в JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "id": 2,
      "session": "CC033C4629BAEF3852CFE27A"
    }

Работа с текущей сессией


Как получить информацию о текущей сессии

  1. Отправьте GET-запрос с номером текущей сессии: 

    Получить информацию о текущей сессии
    curl -X GET 'https://domain.com/api/auth/v3/whoami' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. В ответ будет получен JSON-объект вида: 

    Ответ в JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "lang": "ru",
      "owner_email": "client@example.com",
      "owner_id": 2,
      "roles": [
        "@user"
      ],
      "ses_id": 2,
      "session": "CC033C4629BAEF3852CFE27A",
      "trustee_email": "client@example.com",
      "trustee_id": 2
    }

Завершение сессии

Мы рекомендуем принудительно прерывать сессию пользователя после завершения работы с API: 

  1. Отправьте DELETE-запрос с номером сессии: 

    Закрыть сессию
    curl -X DELETE 'https://domain.com/api/auth/v3/session/CC033C4629BAEF3852CFE27A' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. В ответ будет получен JSON-объект вида: 

    Ответ в JSON
    {
      "status": "ok"
    }
  3. При попытке использовать удалённую сессию будет получен JSON-объект вида: 

    Сессия не найдена
    {
      "error": {
        "code": 3002,
        "msg": "Session not found"
      }
    }

Коды ошибок


Код ошибкиHTTP кодТип ошибкиВозвращаемое описаниеОписание
3001401AuthInvalidLoginInvalid login

Для авторизации указан неверный логин или пароль. 

3002401AuthSessionNotFoundSession not foundПередан несуществующий код сессии. 
3003404AuthUserNotFoundUser not foundУказанный пользователь не найден. 
3004409AuthUserAlreadyExistUser already existsТакой пользователь уже существует. 
3005403AuthAccessDeniedAccess denied

Недостаточно прав для выполнения функции. 

3007401IspSessionHeaderNotFoundSession header was not setВ заголовке запроса не передан код сессии пользователя. 
3014403AccessForbiddenAccess forbiddenУказанному пользователю запрещён доступ. 
3015401TooFrequentLoginAttemptsToo frequent login attemptsПревышено число неудачных попыток авторизации. 
3016404AuthKeyNotFoundTemporary identification key not foundУказанный одноразовый ключ авторизации не существует или уже был использован. 
3018403AuthAccountDisabledAccount is disabledУчётная запись пользователя заблокирована. 
3051404ProductNotFoundProduct not found

Передано неверное значение параметра типа экземпляра продукта.

3080404InstanceNotFoundInstance not foundЭкземпляр Vepp с указанным id не существует.