Разработчики нередко приходят к мысли создать API на Python (англ. Application Programming Interface — программный интерфейс приложения). Если вы лишь недавно повстречались с этим термином, обладаете идеей для своего такого ПО и хотите разобраться, как устроено содержимое проекта, статья познакомит с базовой терминологией и проведет от первого шага с подключением фреймворка FastAPI и до HTTP-запроса.

Немного про HTTP

Для тех, кто не знаком с концепцией, расскажу вкратце: это способ обмена данными от сервера к клиенту и обратно. Мы пользуемся им каждый день в подавляющем большинстве сервисов:

Этот «протокол передачи гипертекста» (англ. HyperText Transfer Protocol) стал популярен в 90-х и сегодня де-факто является стандартом обмена между устройствами. Развертывая простенький проект на Django, вы тоже, кстати, пользуетесь HTTP.

Подсказка: Если вам интересна миграция с low-code CMS на Django, изучите эту статью.

Вы наверняка уже слышали про классические типы запросов: GET (получить) и POST (создать). Среди прочих выделю еще DELETE (удалить), INSERT (вставить) и UPDATE (обновить). Один из них мы реализуем своими руками в этом гайде.

Деплой FastAPI на Railway

Чтобы вы могли быстрее пощупать новоиспеченное ПО, я использую фреймворк FastAPI. Создавая проект на его базе, вы подключите автоматом:

— main.py — главный для разработчика файл, ответственный за HTTP-запросы;
— requirements.txt, содержащий список всех необходимых сторонних инструментов с версиями;
— .gitignore, описывающий файлы, которые при коммите стоит игнорировать, например, директорию виртуального окружения;
— railway.json помогает серверу схватить настройки проекта и запускать API автоматически после каждого обновления.

Клонировав этот код с маркетплейса, вы найдете все необходимое, чтобы сдружиться с Railway. Это условно бесплатный сервис для развертывания ваших приложений, то есть круглосуточно доступный сервер. Он пришел отчасти на замену Heroku и предлагает любому пользователю 5 демо-долларов, которые расходуются довольно медленно, по паре центов в день.

В следующие 3-5 минут проект саморазвернется: установятся библиотеки, настроится триггер для пересборки API в случае коммита. Давайте вместе пройдемся по логам и научимся их читать при проблемах в будущем:

Первое, что отдает нам Railway — это перечень запускаемых команд:

Затем устанавливаются все необходимые библиотеки:

Система уведомляет об успешно установленных инструментах:

Подсказка: Если вы намереваетесь повторить мой путь с другим шаблоном, то наверняка столкнетесь с крушением билда. Сборки устаревают быстро, конфликт зависимостей никто не отменял, и прежде чем темплейт заработал, мне пришлось пройти 4 попытки по другим ссылкам.

Деплой успешно выполнен:

В разделе Settings блока FastAPI вы найдете перманентный URL, ведущий на поддомен Railway. Он позволит обращаться к вашему API с любого устройства:

По умолчанию в главном файле проекта из методов только / (root-метод). Выглядит он таким образом, вскоре мы познакомимся поближе:

Перейдя по ссылке fastapi-production-fd50.up.railway.app я получу hello-world-приветствие:

Cоздаем глагол GET

Для разработки собственных методов мне понадобится запустить этот же проект на ноутбуке. Потому теперь я клонирую себе репозиторий (он добавился в листинг моего аккаунта на GitHub):

Открыв эту новую директорию в VSCode, создаю виртуальное окружение и устанавливаю инструменты:

Чтобы файлы fastapi_env не попали в репозиторий и не усложнили тем самым чтение коммита, исключим эту подпапку с помощью .gitignore, добавив строку:

Для запуска API в режиме отладки на своей машине используется специальная утилита hypercorn:

Теперь тот же root-метод доступен по адресу 127.0.0.1:8000:

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

Это тело запроса для библиотеки requests, и оно содержит смещение (сервер расположен где-то в UTC±0:00, то есть полночь там наступает на три часа раньше, чем в Москве):

Каждый раз обсчитывать смещение при тестах неудобно, особенно, когда выгружаешь логи за период, не равный 24 часам. Так что давайте создадим метод, чтобы рассчитывал смещение. Для этого в main.py добавлю декоратор @app.get("/get") (на самом деле, вместо get можно поставить любое слово) и функцию get_time():

Первый собственный метод готов. Теперь проверим его работу, перейдя по ссылке http://127.0.0.1:8000/get:

Создав коммит с такой функцией, вы получите автоматический редеплой от Railway и работающий метод /get по ссылке fastapi-production-fd50.up.railway.app/get. Вместо datetime.datetime.now() несложно подставить другое интересующее время и получить смещение от него.

Заключение

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

— Найти сервер, на котором интерфейс будет базироваться. Свой ноутбук — это не сервер для продакшена;
— Выбрать фреймворк для API (например, FastAPI / litestar);
— Создать проект фреймворка по документации или с темплейта и развернуть его на сервере;
— Описать собственные методы;
— Погордиться собой, ведь свой эндпоинт — это очень круто!

Познакомиться с моим проектом вы можете на GitHub.