У московской службы доставки питьевой воды в бутылях по 19 литров появился единый программный интерфейс на FastAPI: от него работают новое мобильное приложение, партнёры и курьеры. Разработка API — работа Евгения Рослякова. Сайтами и их серверной частью он занимается с 2016 года, оформлен как самозанятый, подписывает договор, для юрлиц даёт закрывающие документы и берёт заказы в Москве и удалённо.
Компания возит воду по Москве и области. Заказы шли через сайт и по телефону. Среди клиентов много офисов, и два офисных центра с сервисами для арендаторов захотели заказывать воду автоматически, без звонков администратору.
Мешал старый сайт. Данные он отдавал кусками: адреса в одном месте, цены в другом, а остаток бутылей у клиента не получить вообще. Описания нигде не было, программист партнёра гадал, что значит каждое поле. Параллельно делали мобильное приложение, и ему нужен был надёжный источник данных.
Цель такая: интерфейс, на который можно опереться и приложению, и партнёрам, и курьерской программе. У каждого свой ограниченный доступ, изменения не ломают чужие интеграции, описание лежит в открытом виде.
У этого товара есть особенность: тару возвращают. Поэтому в данных нужен не только заказ, но и баланс бутылей у клиента.
Начал с карты данных. Вместе с диспетчерами выписал, что реально происходит в работе: адрес доставки, товар, интервал, заказ, возврат тары, баланс бутылей. Из этого получился набор ресурсов.
Сервис написан на FastAPI. Он собирает схему из описаний полей, поэтому документация в формате OpenAPI не пишется отдельно и не расходится с кодом. Интерфейс построен по принципам REST: адреса, товары, интервалы доставки, заказы и возврат тары — отдельные ресурсы с понятными методами. Баланс бутылей отдаётся вместе с профилем клиента. Создание заказа защищено ключом идемпотентности: если партнёр из-за обрыва связи отправит запрос дважды, заказ появится один раз.
Доступ закрыт через OAuth 2.0. Мобильное приложение входит по схеме с PKCE, токены живут недолго и обновляются сами. Партнёры получают свои ключи по схеме client credentials и видят только свои заказы и только нужные методы. Права разведены: партнёр не может поменять цену, курьер не видит чужих клиентов.
Для партнёров поднял песочницу с тестовыми данными, чтобы пробовать заказ без настоящей воды. Ввёл версии: старое поведение остаётся на прежнем адресе, пока интеграторы не перейдут. Добавил лимиты запросов и вебхуки о смене статуса заказа, чтобы партнёрам не приходилось опрашивать сервис каждую минуту.
Веб-API для курьерского приложения вышло отдельным: маршрут на день, отметка о доставке, приём пустых бутылей. Старый сайт переключили на тот же интерфейс, чтобы данные не жили в двух местах.
У службы доставки появился единый источник данных. Приложение, сайт и курьерская программа берут информацию из одного места и показывают одно и то же. Споры вида «в приложении одно, у диспетчера другое» прекратились, особенно по бутылям: баланс виден клиенту сразу, а не после звонка.
Партнёры подключаются сами. Программисту офисного центра достаточно открыть документацию, получить ключ для песочницы и попробовать заказ. Вопросов в службу вроде «что значит это поле» стало заметно меньше, а вебхуки избавили от постоянных запросов статуса.
Изменения теперь не пугают. Новое поле или метод выходят в новой версии, а старые интеграции работают, пока их владельцы не успеют обновиться.
Одно допущение. Лимиты запросов я выставил по оценке нагрузки, а не по длинной статистике, поэтому через несколько месяцев работы их стоит пересмотреть. Проверку под высокой нагрузкой перед летней жарой, когда воду заказывают чаще, договорились провести отдельно.
Если у вас есть приложение, сайт или партнёры, которым нужен внятный интерфейс к данным, оставьте заявку или сообщение на freelance.ru и опишите, откуда данные берутся сейчас. С этого описания и начнём.
