API Scoring Service

API сервис автоматизированной оценки переданных данных.

Системные требования

• Python версии 3.12 или выше (исключая версию 3.12.5, на ней не работает black)
• Poetry версии 1.8.3 или выше
• Redis версии 7.0 или выше

Установка

1. Склонируйте репозиторий:

git clone git@github.com:MegaDoge1337/otus-scoring-api.git

2. Перейдите в директорию с проектом:

cd otus-scoring-api

3. Установите зависимости:

poery install

4. Запустите Redis, docker-compose.yml для развертывания в минимальном варианте приложен в репозитории (необходима доступность по адресу localhost с портом 6379, при необходимости параметры можно изменить в исходном коде файла api.py):

docker-compose up -d

Проверка и тестирование

Для запуска инструментов форматирования или тестов используйте Makefile

• Запуск линтера

make lint

• Запуск форматирования

make format

• Сортировка импортов

make import-sort

• Запуск модульных тестов

make unit-test

• Запуск функциональных тестов (предварительно запустите Redis)

make func-test

Запуск

Для запуска приложения выполните скрипт api.py:

python api.py

По умолчанию прослушивается порт 8080, чтобы выбрать другой порт, используйте ключ -p или --port:

python api.py -p 8888

python api.py --port 8888

По умолчанию лог пишется в консоль, чтобы логгировать работу приложения в файл, используйте ключ -l или --log:

python api.py -l log.log

python api.py --log log.log

Эксплуатация

Сервис, по умолчанию, предоставляет доступ по маршруту /method. Формат запроса следующий:

{
  "account": "horns&hoofs",         # имя аккаунта (строка, поле опционально, может быть пустым)
  "login": "h&f",                   # логин аккаунта (строка, поле обязательно, может быть пустым)
  "method": "online_score",         # метод (строка, поле обязательно, может быть пустым), подробнее см. раздел Методы
  "token": "...",                   # токен аутентификации (строка, поле обязательно, может быть пустым), подробнее см. раздел Аутентификация
  "arguments": {...}                # аргументы метода (словарь/json-объект, поле обязательно, может быть пустым), подробнее см. раздел Методы
}

Методы

Сервис обеспечивает работу двух методов:

• online_score - выполнение скоринга
• clients_interests - получение списка пользовательских интересов по темам

Аргументы для методов передаются вместе с телом запроса, в поле argumets.

Метод online_score

Формат запроса для метода online_score:

{
  ...

  "arguments": {
    "phone": "71234567890",       # номер телефона (строка или число, длиной 11, начинается с 7, поле опционально, может быть пустым)
    "email": "example@mail.com",  # адрес электронной почты (строка, в которой есть @, поле опционально, может быть пустым)
    "first_name": "Иван",         # имя (строка, поле опционально, может быть пустым)
    "last_name": "Иванов",        # фамилия (строка, поле опционально, может быть пустым)
    "birthday": "01.01.1990",     # дата рождения (формате DD.MM.YYYY, с которой прошло не больше 70 лет, поле опционально, может быть пустым)
    "gender": 1                   # пол (число 0, 1 или 2, поле опционально, может быть пустым)
  }

  ...
}

Запрос будет выполнен, если присутсвует хоть одна пара phone-email, first_name-last_name, gender-birthday с непустыми значениями (иначе вернется ошибка No valid pair for request).

В случае успешного выполнения возвращает в ответ результат скоринга:

{
  "response": {
    "score": 5.0
  },
  "code": 200
}

Метод clients_interests

Формат запроса для метода clients_interests:

{
  ...

  "arguments": {
    "client_ids": [1, 2, 3],      # идентификаторы клиентов (массив чисел, поле обязательно, не пустое)
    "date": "20.07.2017"          # дата (в формате DD.MM.YYYY, поле опционально, может быть пустым)
  }

  ...
}

В случае успешного выполнения возвращает в ответ результат скоринга:

{
  "response": {
    "1": ["books", "hi-tech"],
    "2": ["pets", "tv"],
    "3": ["travel", "music"]
  },
  "code": 200
}

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

Токен аутентификации может генерировать для пользователя или для администратора:

# Токен пользователя
hashlib.sha512((request.account + request.login + SALT).encode('utf-8')).hexdigest()

# Токен администратора
hashlib.sha512((datetime.datetime.now().strftime("%Y%m%d%H") + ADMIN_SALT).encode('utf-8')).hexdigest()

Значения SALT и ADMIN_SALT определяются в коде приложения.

При использовании учетной записи администратора важно учитывать следующие особенности:

• для каждого запроса от имени администратора в поле login следует использовать логин, определенный в коде приложения, в переменной ADMIN_LOGIN
• для каждого запроса к online_score с правами администратора значение score будет равно 42

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

Если запрос к сервису имеет неверный формат, в ответ вернется сообщение с кодом ошибки и сообщением об ошибке, например:

{
  "error": "Field `method` is required\nField `phone` must be 11 charactes long...",
  "code": 422
}