«Твой API вообще не RESTful»

Такую претензию один разработчик озвучил аналитику. Причиной возмущения были следующие решения:
🟣 использование POST вместо GET для получения данных
🟣 использование глагола в URL, типа /approve

Ирония ситуации была в том, что в проекте оба эти «нарушения» RESTful подхода уже не раз встречались, а разработчик и аналитик оба только недавно пришли в команду.

Давайте разберемся, насколько претензии были правомерны.

🤓 Вообще REST создавался не для сложных бизнес-систем с кучей операций, а как архитектурный стиль (то есть набор правил) для гипермедийных систем типа Википедии.

Когда мы пытаемся уложить логику бизнес-операций и взаимодействия микросервисов в чистый REST, то неизбежно сталкиваемся со сложностями.
Даже простой /login уже не RESTful 🤷‍♀️

Классический RESTful возможен там, где мы имеем дело с набором статичных ресурсов, которым достаточно CRUD-операций. Например, хранилище файлов S3 или MVP сервиса стриминга музыки.

🤔 Может, если у нас бизнес-процессы, то нам отказаться от REST и делать эндпойнты с действиями?

/update
/approve

Такой подход называется RPC over REST. Он выглядит как REST, но отталкивается не от ресурсов, а от действий (процедур). При этом методы http (GET/PUT/DELETE) могут не использоваться, всё может реализовываться через POST.

Среди публичных API не встречала этот подход в чистом виде, но эндпойнтов с действиями много например в Ozon Seller API:

POST /v2/products/delete
POST /v1/product/archive
POST /v1/product/unarchive

Так, а если мне список документов нужно получить, то это POST /getDocuments ? Как-то непривычно. Удобно же со старым добрым :

GET /documents
GET /document/{id}

А если мне нужно сделать поиск (фильтрацию) документов по куче полей? Все их в url GET класть кажется плохой идеей.
Ответы GET запросов могут кэшироваться на промежуточных узлах, а зачем такой специфический запрос кэшировать? Да и ограничение на длину запроса может сработать.

Поэтому делают POST /documents/search
Это удобно и часто используется.

Так что с первой претензией разобрались, снимается 😊

Вернемся к глаголам.

🤔 Теоретически часть действий можно завернуть в статусы документа и вместо POST /document/{id}/approve делать:

PATCH /document/{id}

{
  "status": "APPROVED"
}

Но не для всех операций сработает. Да и читаемость может сильно пострадать.

Есть гибридный подход, который работает с ресурсами и методами HTTP, но может иметь действия в URL и использовать POST для сложных запросов чтения.

Такой подход называют Pragmatic REST. Его главная цель — понятность и удобство. Pragmatic REST берет всё лучшее из REST, но позволяет отступить от строгих правил, если это необходимо для ясности и удобства ☺️

Скорее всего на вашем проекте используется именно он, даже если сам термин не применяется.

Разработчик с аналитиком в итоге пришли к консенсусу по этой задаче, заменив один из POST-ов на GET, а остальное оставив в первоначальном виде. Но это был не последний их спор.

Кстати, есть еще холиварный вопрос: по классике REST-подхода метод PUT используется для полного обновления ресурса, а PATCH для частичного. Но на многих проектах я встречала PUT для частичного обновления нескольких полей, и всем было ок. Голосуйте в опросе ниже, на чьей вы стороне 😃

Были ли у вас ситуации с дискуссиями вокруг разрабатываемого API?

4️⃣5️⃣6️⃣

Как WB сделал «Поиск по фото»

Продолжаю рассказывать про прикольные проекты коллег. В этот раз прикольную фичу — поиск по фото, которой я сам частенько пользуюсь. Особенно если нашел какую-то прикольную вещь в рилсах, или буквально недавно нашел чайник-термос в одном заведении.

С точки зрения юзера схема супер простая: Заскринил — загрузил — выделил нужный объект — выбрал нужный товар. Кстати прикольно, что у нас есть OCR по объектам, я такого в других местах не встречал. Можно по одному фото сразу несколько вещей найти.

Под капотом там не просто CLIP, сначала YOLO вырезает объект, OCR снимает артикулы/текст, потом SigLIP-эмбеддинги улетают в векторный поиск Qdrant (HNSW). Товары лежат уже в эмбеддингах заранее.

Самое интересное — мультимодальная логика: поиск живёт не только в изображении. Фото обогащают тегами, которые заранее сгенерированы LLM офлайн по описаниям и визуальным признакам.

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

➡️ Почитать можно тут


❗Ставьте 🔥 огонек если пользуетесь поиском по фото

MADE IN @researchoshnaya