Backend Checklist — День 8: Resource-based URLs

Почему вообще важно, назван endpoint в честь invoice или в честь действия, которое нужно с ним выполнить, если оба возвращают абсолютно одинаковый JSON? Response одинаковый. Но всё, что находится между client и server, работает по-разному.

Два места — одна задача

HTTP определяет methods для обозначения цели request, а URI используется для идентификации resource. Если поместить action в path, то path начинает отвечать на вопрос, на который уже должен отвечать method, и две части одной request line могут противоречить друг другу.

Path перестаёт разрастаться

Если называть resource, то все новые действия с invoice будут определяться через method, а не через очередной endpoint. В итоге API растёт вместе с количеством resources, а не с количеством добавленных features.

Что видит cache

Response может кэшироваться, если используется GET или HEAD. POST и PATCH подходят для этого только при наличии freshness information и соответствующего Content-Location header, что практически нигде не реализуется. Поэтому endpoint, названный в честь action, в итоге ничего не сохраняет на edge, и каждый read request проходит весь путь до origin server.

Обратная ситуация ещё опаснее

HTTP method считается safe, если он не изменяет состояние server. Браузеры могут выполнять prefetch, полагаясь на это правило, а crawlers также рассчитывают на него. Если направить их на endpoint, который что-то удаляет, — они это удалят.

Ничто не обеспечивает это автоматически

Nginx не может проверить, что route предназначен только для чтения. Framework тоже не может этого проверить. Это правило соблюдается лишь потому, что handler за конкретным route действительно ведёт себя соответствующим образом.

URL — это имя, а не инструкция

Если path уже говорит, что должно произойти, request сообщает одно и то же дважды. А всё, что находится между client и server, будет ориентироваться на ту часть request, для чтения которой оно было спроектировано.

👉 @BackendPortal

Эффективное освоение алгоритмов через паттерны LeetCode

Ресурс группирует задачи LeetCode по фундаментальным паттернам решения, превращая разрозненные задачи в понятную систему подходов.

Каждый паттерн объяснён, подкреплён примерами и визуализациями что помогает не просто «зубрить» задачи, а понимать сам подход, который легко переносится на новые задачи.

Есть треки для пошаговой подготовки от новичка до продвинутого. Это экономит время: вместо хаотичного выбора задач вы двигаетесь по структурному пути, который закрывает все ключевые темы для собесов.

👉 @BackendPortal

Backend Checklist — День 9: Idempotency

Клиенты повторяют запросы. Request может завершиться по timeout, соединение может оборваться, пользователь может снова нажать кнопку — и один и тот же request попадёт на server дважды.

Request считается idempotent, если его повторное выполнение безопасно. Отправите его один раз или десять — server останется в одном и том же состоянии.

Какие методы гарантируют idempotency?

GET, PUT и DELETE.

Повторно получите invoice, снова запишите тот же invoice или снова удалите его — итоговое состояние server останется тем же. POST такой гарантии не даёт. Каждый POST — это новая операция, поэтому два запроса могут означать две оплаты, два заказа или две строки в базе данных.

Но одинаковый результат не означает одинаковый response

Удалите invoice — получите 204. Попробуйте удалить его ещё раз — получите 404.

Responses разные, но invoice в обоих случаях остаётся удалённым. Idempotency относится к состоянию server, а не к ответу, который вы получаете.

Ваш proxy уже полагается на это

Если server падает до отправки response, reverse proxy может повторить GET, PUT или DELETE на другом server, но не станет автоматически повторять POST. Он ориентируется на HTTP method и доверяет его семантике.

Поэтому главная проблема — POST

Платёж завершается по timeout через 30 секунд. На 29-й секунде транзакция уже прошла, пользователь снова нажимает «Оплатить» — и в результате получает два списания.

Для этого используется idempotency key. Client отправляет уникальный key, server сохраняет первый результат под этим ключом, а каждый повторный request с тем же key получает сохранённый результат вместо повторного выполнения операции.

Где HTTP method может гарантировать idempotency — это делает method. Где не может — эту гарантию обеспечивает idempotency key. Проверьте proxy_next_upstream в конфигурации Nginx. Он уже определяет, какие requests можно повторять при определённых ошибках.

👉 @BackendPortal

Приоритеты плохого разработчика 😪

👉 @BackendPortal

Backend Checklist — День 10: Status Codes

Request завершился ошибкой. Что вернуть: 400, 401, 403, 404 или 422? Большинство API используют тот status code, который кажется наиболее знакомым. Именно с этой привычки и начинаются незаметные баги.

Первая цифра передаёт основную суть:
1xx → request всё ещё обрабатывается
2xx → всё прошло успешно
3xx → resource перемещён или требуется перенаправление
4xx → ошибка на стороне client
5xx → server столкнулся с ошибкой при обработке request

А дальше начинаются пары, которые часто путают:
401 vs 403:

401 = «Я пока не знаю, кто вы».
403 = «Я знаю, кто вы, но доступ вам всё равно запрещён».
400 vs 422:
400 = request не удалось корректно разобрать.
422 = request разобран, но переданные значения невалидны.
301 vs 307:
301 означает постоянный redirect и может кэшироваться.
307 сохраняет исходные HTTP method и body.

Главное правило: status code — это обещание о том, что произошло, а не просто label, который добавляется к response постфактум.

Верните 200 с ошибкой в body — и вы только что сообщили всем retry-механизмам, alerts и uptime checks, что всё в порядке.

Выбирайте status code исходя из того, что действительно произошло, а не из того, какой оказался под рукой.

👉 @BackendPortal

AI-агенты и инфраструктура

Вашему coding agent не нужно знать, где именно выполняется команда: локально, внутри Docker или в удалённой sandbox.

Предоставьте каждому execution backend одинаковый интерфейс, а harness пусть работает с ними одинаково.

👉 @BackendPortal

Нашёл сокровищницу для новичков в Python

Удобная шпаргалка, где в одном месте собрали всё, что чаще всего приходится вспоминать: типы данных, операции, строки, списки, словари, методы и база конструкции языка.

Хорошая штука, можно держать рядом во время работы, обучения и практики.

Забираем в закладки ❤️

👉 @BackendPortal

Backend Checklist — День 11: API Versioning

Вы выпустили v1. Теперь нужно изменить структуру response, не сломав существующих clients. Где указывать версию API?

Есть три варианта:

• Path: /v1/users
• Header: Api-Version: 2
• Query: /users?api-version=2

Все три подхода работают. Главное различие — какие компоненты системы могут видеть версию.

• Path: версия видна routers, proxies, logs и caches. Простой и широко используемый вариант.
• Header: позволяет сохранить URL чистыми, но cache может не различать версии, если не использовать Vary.
• Query: версия хорошо видна инфраструктуре, но смешивается с параметрами фильтрации и pagination.

Главная опасность — caching

Если версия передаётся через header, а cache формирует ключ только по URL, client с v2 может получить закэшированный response от v1.

Версия API — это обещание о структуре response. Убедитесь, что cache умеет различать разные версии API.

👉 @BackendPortal

Краткая шпаргалка по Kotlin

Синтаксис, типы данных, условия, циклы, коллекции, функции, классы, null safety, generics, lambda и другие конструкции.

Сохраняем в закладки 😏

👉 @BackendPortal