Разбираем ответы

❌ /orders?userId=789
Это фильтрация коллекции заказов по полю userId, и технически работает, но:
query-параметры обычно применяются для опциональных фильтров, сортировки, пагинации, а не для обязательного выбора ресурса.

❌ /getOrdersForUser/789
Нарушает REST. В URI не должно быть глаголов. Путь должен описывать ресурсы, а не действия. Такой формат превращает API в RPC‑подобный стиль, а не в ресурс‑ориентированный.

❌ /orders/user/789
Здесь нарушена иерархия. Правильный порядок: сначала родитель (пользователь), затем дочерний ресурс (заказы).

В дизайне REST API порядок сегментов в URI отражает иерархию владения ресурсов — кто «контейнер», а кто «контейнеризованный». Пользователь (user) — это «агрегатный корень» для своих заказов: все заказы принадлежат конкретному пользователю. Когда вы пишете /users/789/orders, вы однозначно говорите: «Возьми пользователя с ID 789 и верни его заказы».

Это лучше, чем просто фильтровать всю коллекцию заказов по userId, потому что:
✔️Явно выражена связь «пользователь → его заказы».
✔️Проще настраивать авторизацию — сначала проверяешь доступ к пользователю, потом возвращаешь связанные заказы.
✔️Легче кешировать и документировать вложенные ресурсы.

Если бы вы сделали наоборот — /orders/… первым — то вы отображали бы сам заказ как основной ресурс, а не контекст его принадлежности. Для случаев, когда вам нужен конкретный заказ, используют именно /orders/{orderId}.
А для списка заказов конкретного пользователя более естественно и семантично смотреть через контекст пользователя.

✅ Поэтому правильный ответ
/users/789/orders

#rest #api

HTTP‑запрос состоит из:

1️⃣ Request‑Line
<Метод> <URI> <Версия протокола>

2️⃣ Заголовки (Headers)
Набор строк вида Имя: Значение. Передают метаданные (формат данных, авторизация и т. д.).

3️⃣ Тело запроса (Body) —
Данные, передаваемые серверу (JSON, файлы и пр.). Появляется у методов POST, PUT, PATCH и др.

Пример HTTP‑запроса:

POST /users HTTP/1.1
Host: api.example.com
User-Agent: curl/7.68.0
Accept: application/json
Content-Type: application/json
Content-Length: 48

{
"name": "Иван",
"email": "ivan@example.com"
}

#api #http #rest

Всем привет! 👋
С вами Вера, основатель AnalystCore.

Ранее я писала, что готовлю курс по документации. Расскажу немного о процессе, что делаю сейчас в этом направлении.

За 8 лет работы в разных компаниях и командах я выработала свой удачный шаблон ведения документации в Confluence (он применим и для других подобных систем). Я собирала лучшие подходы из разных проектов, дополняла, отбрасывала лишнее и проверяла это всё на реальных задачах.

📝 Сейчас я снова проверяю этот шаблон на прочность: решила описать документацию с нуля, чтобы убедиться, что он покрывает большинство вопросов команд.

💡 Шаблон учитывает:
— где заканчивается бизнес-потребность и начинается техническое описание;
— как писать так, чтобы было понятно и разработчику, и менеджеру;
— как оформить структуру, чтобы через полгода всё было читаемо и легко искалось (а не «открой конфлюенс и вычитывай весь документ»).
Плюс у меня есть своя методика:
📌 что писать в Jira,
📌 что оставлять в Confluence,
📌 и как сделать так, чтобы задачи в Jira сами по себе были полезным источником информации — а не просто «указателем на документацию». Спойлер: помимо ссылки на доку всё-таки пару предложений стоит написать😉.

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

👉 https://forms.gle/FbSbBCbKoiY53edV7

Вы реально можете повлиять на программу! Например, хотите ли вы:
— шаблоны для Confluence?
— схемы связки Jira + Confluence?
— готовые формулировки для Use Case и описания API?
💬 Напишите в опросе, что вас волнует, и я постараюсь включить это в курс.

HTTP‑методы

Метод — это команда, которая говорит серверу, что сделать с ресурсом.

Например:
GET /users/123 HTTP/1.1
GET — «выдай мне представление ресурса по адресу /users/123».

Основные методы HTTP:
GET — получить ресурс
«Покажи профиль пользователя»

POST — создать новый ресурс или выполнить операцию
«Создай заказ», «Авторизуйся»

PUT — создать или полностью заменить ресурс
«Полностью обнови профиль»

PATCH — частично обновить ресурс
«Измени только e‑mail»

DELETE — удалить ресурс
«Удали заказ № 123»

HEAD — получить только заголовки ресурса (без тела)
OPTIONS — узнать, какие методы поддерживает ресурс
CONNECT — установить туннель (обычно для HTTPS через прокси)
TRACE — вернуть полученный запрос (для отладки)

На собеседованиях в секции про API почти всегда задают вопрос:
💬 «Какие методы считаются безопасными и идемпотентными?»
Что значит «безопасный» и «идемпотентный», почему это важно для надёжных API и какие методы попадают в каждую категорию — разберём в следующем посте. Не пропустите! 😉

#api #http #rest

🔐 «Безопасный» и «идемпотентный» — что это значит для HTTP‑методов?

Когда на собеседовании спрашивают про безопасность и идемпотентность, речь не об HTTPS и не про авторизацию. Это про семантику методов — как они должны себя вести.

БЕЗОПАСНЫЕ методы
Метод считается безопасным, если он ничего не меняет на сервере, а только читает информацию.

✅ GET /users/123 Получить данные пользователя. Хоть тысячу раз повторяйте — состояние сервера останется прежним.
✅ HEAD /reports/2023 Проверить, есть ли отчёт за 2023 год. Возвращает только заголовки, без данных — ничего не изменится.
❌ POST /payments { "amount": 100 } Создаёт новый платёж → меняет данные на сервере, небезопасный.
❌ PUT /users/123 { "name": "Иван" } Изменяет имя пользователя → состояние данных поменялось, не безопасный.
❌ PATCH /users/123 { "email": "new_email@gmail.com" } Обновляет только email пользователя → данные на сервере изменяются, не безопасный.
❌ DELETE /orders/555 Удаляет заказ → меняет данные, значит не безопасный.

ИДЕМПОТЕНТНЫЕ методы
Идемпотентный метод — это когда повторный вызов с теми же параметрами даёт тот же результат, что и первый.

✅ GET /products/10 Хоть сколько раз вызывайте — всегда вернёт одни и те же данные товара.
✅ HEAD /products/10 Повторно возвращает только заголовки ресурса, результат не меняется.
✅ PUT /users/123 { "name": "Иван" } Каждый раз устанавливает имя пользователя на "Иван". Итоговое состояние всегда одинаковое.
✅ DELETE /orders/555 При первом вызове удалит заказ, повторно вернёт 404 — в итоге заказа нет, состояние не меняется.
❌ POST /payments { "amount": 100 } Каждый раз создаётся новый платёж → состояние сервера меняется при каждом вызове.
❌ PATCH /users/123 { "points": "+10" } Каждый повтор добавляет пользователю 10 баллов → состояние каждый раз новое.

Есть и другие методы (OPTIONS, CONNECT, TRACE), но они не влияют на изменение ресурсов и редко обсуждаются на интервью по REST API.

❗️ Запомнить просто:
Безопасный метод 👉 ничего не меняет на сервере, только чтение.
Идемпотентный метод 👉 повтор запроса не меняет итоговое состояние ресурса.

#api #rest #http #interview

⚙️ Как сделать POST-запрос идемпотентным?

На собеседованиях спрашивают про идемпотентность POST не для «галочки», а чтобы проверить, что вы понимаете реальные проблемы надёжности API.

❌ POST — не идемпотентный метод. Повторный вызов создаёт новый ресурс или действие. Например, если отправить форму платежа дважды, то оплата пройдёт два раза 😞

Это проблема. Если соединение оборвалось, клиент повторяет запрос и получает нежелательный дубликат. Но есть решение:
🔑 Используйте idempotency key (ключ идемпотентности).

Как это работает?

1️⃣ Генерируется ключ и передаётся в запросе:
– Клиент может сам создать ключ и передать его в заголовке.
– Либо сервер возвращает ключ при открытии формы, и фронт шлёт именно его.

2️⃣ Сервер проверяет ключ в запросе:
– Если запрос с таким ключом уже был, сервер не создаёт новую запись, а возвращает сохранённый результат первого запроса.
– Если ключ новый — выполняет действие и сохраняет результат вместе с этим ключом.

Таким образом, POST-запрос можно сделать идемпотентным с помощью ключа идемпотентности. Повторное выполнение ничего не меняет, а просто отдаёт прежний результат.

#api #rest #interview

Разбираем ответы

❌ /comments?articleId=42
Технически — корректно. comments выступает корневой коллекцией, а ?articleId=42 работает как фильтр. Однако по REST рекомендуется показывать вложенность прямо в пути, чтобы сразу было видно, к чему комментарии принадлежат. Они не живут сами по себе, а относятся к конкретной статье.

❌ /articles/comments/42
Нарушен порядок. Здесь непонятно, что такое comments/42. Это все комментарии статьи 42 или комментарий 42? URL двусмыслен 😞.

❌ /articles/42?comments
Параметр comments без значения, он ничего не уточняет. Если указываете параметр, то пишите, чему он должен быть равен. И помним, query-параметры используем в основном для фильтрации, сортировки, но не для получения вложенного ресурса.

❌ /comments/42/articles
Инвертирована иерархия. Тут выглядит так, будто у комментария 42 есть статьи. Логически неверно. У нас у статьи 42 есть комментарии.

✅ Правильный ответ
/articles/42/comments
Сначала ресурс «статья» (/articles/42), а внутри него подресурс comments. Так мы получим комментарии к конкретной статье.

#rest #api

Привет! 👋
С вами Вера, основатель AnalystCore.

REST, API, методы… Всё это, конечно, важно. Но есть тема, которую системные аналитики будто бы знают, но на практике оказывается, всё гораздо сложнее. Это требования.

Давайте сделаем паузу в теме REST и вернёмся к самому началу.
Потому что всё начинается именно с требований. Без них — всё остальное теряет смысл.

💬 Требования — это то, с чего начинается любая задача системного аналитика.
Но, если честно, эту тему часто недооценивают.
Кажется, ну что там сложного? Спросил, записал — готово.
А на деле:
📌 Требования бывают противоречивыми.
📌 Их нельзя просто «записать» — их нужно вытаскивать, распутывать, уточнять.
📌 То, как вы проработаете требования, влияет на всю реализацию задачи.
📌 Часто именно «плохие требования» становятся причиной багов и переделок.
И самое интересное — чем дольше вы работаете аналитиком, тем больше понимаете, сколько всего ещё не знаете про требования 😅

📆 В ближайшие недели будем вместе разбирать:
— кейсы, в которых не всё так однозначно,
— полезная теория и техники,
— лайфхаки и шпаргалки,
— подводные камни, с которыми вы сами могли не раз сталкиваться.

Оставайтесь с нами — будет интересно 😉

#requirements

Задача❓ Добавить новое обязательное поле «Цель кредита» в форму заявки на кредит.

💬 Бизнес говорит:

Нужно добавить поле «Цель кредита» в заявку. Это важно для отчётности. Сделайте обязательно для заполнения. Значения — стандартные.

Кажется, всё понятно. Но давайте подумаем — действительно ли тут всё так просто?

❓Вопрос к вам:
Как бы вы подошли к этой задаче как системный аналитик?
Над чем бы задумались? Что уточнили бы у заказчика, команды или у себя самого?

✍️ Напишите свои мысли в комментариях.
А в следующем посте мы поделимся своей версией.

Не пропустите.

#requirements

Задача❓ Добавить новое обязательное поле «Цель кредита» в форму заявки на кредит.

💬 Исходный запрос от заказчика:

Нужно добавить поле «Цель кредита» в заявку. Это важно для отчётности. Сделайте обязательно для заполнения. Значения — стандартные.

Что уточнить у заказчика, у команды и у самого себя?

1️⃣ Где именно размещаем?
В каком разделе формы?
До или после каких полей?
От этого зависит и UX, и порядок полей в отчёте и пр.

2️⃣ Обязательное — всегда?
Например, если пользователь сохраняет черновик — можно ли сохранить без этого поля?
Или только при финальной отправке заявки?
От этого зависит логика на фронте и бэке, валидация.

3️⃣ Что за «стандартные значения»?
Нужен чёткий справочник:
- Покупка авто
- Ремонт
- Путешествие
- Лечение
- Образование
- Иное (а если выбрали — показывать поле для уточнения?)
❗ А кто владелец справочника? Кто будет поддерживать его актуальность? Если завтра придёт бизнес с новой целью — кто её добавит и в каком виде?

4️⃣ А что делать со старыми заявками?
В старых заявках цели не было, а новое поле будет обязательным, что там проставлять?
Что проставлять в заявках со статусами «Черновик», «В работе» и пр.?

Будем делать маппинг на основе других полей? Возможно, можно подтянуть цель из комментариев, связанных документов, категорий заявки. Будем ли на это тратить силы? Завести ли отдельную задачу на это?

5️⃣ Где должно появиться поле?
В карточке заявки (в вебе и мобильном приложении)
В интерфейсе сотрудников
В отчётах и BI-системах
В БД, API

6️⃣ Как будет использоваться?
Влияет ли цель кредита на автоматическое решение?
Используется ли в отчётах?
Может ли повлиять на ставку / условия?

7️⃣ Есть ли ограничения?
Можно ли выбрать несколько целей?
Валидация для поля «Иное»?

А ещё смотрите классные вопросы, которые написали в комментариях под прошлым постом 👆.

📌 Как видите, даже простая задача может тянуть за собой десятки вопросов, решений и проработок.

В следующем посте расскажем, что ждут от системного аналитика в такой задаче: что он должен передать фронту, бэку, тестировщикам и менеджеру.
Не пропустите 😉

#requirements

📌 Что ждут от системного аналитика в ТЗ на добавление нового поля?

В прошлом посте мы разобрали, какие вопросы стоит задать, прежде чем добавлять новое поле «Цель кредита».
А теперь переходим к тому, что конкретно должен отдать аналитик своей команде.

💡 Сохраняйте, это пригодится в работе💡

🔷 Описание справочника
– Название: Цели кредита
– Список значений
– Указан владелец справочника (кто поддерживает актуальность)

🔷 Описание нового элемента UI
Обычно все элементы интерфейса описываются в виде таблицы. В неё нужно добавить новое поле. Продумайте:
– Где должно быть размещено поле
– В каких случаях оно обязательно
– Укажите возможные значения
– Есть ли значение по умолчанию
– Для цели «Иное» должно отображаться поле ввода «Иное» — описываем условия отображения
– Описываем валидацию для «Иное»: длина, допустимые символы, плейсхолдер и пр.
– Возможные ошибки и условия, когда они появляются
* Не забудьте добавить поле во все экраны, где оно появится. Например, есть ещё система для сотрудников банка, где они тоже могут заполнять и смотреть заявку.

🔷 Макеты
– Отрисуйте макеты сами или вместе с дизайнером
– Не забывайте про адаптивную версию: как поле будет отображаться на телефоне и планшете?
– Как поле выглядит в режиме редактирования и в режиме просмотра?
– Сценарии ошибок, плейсхолдеры, тексты валидаций
– Нужны ли подсказки к полю? (i)

🔷 Спецификация API
– Описание эндпоинта на получение справочника по шаблону (URL, алгоритм работы метода, входные параметры, выходные параметры, коды ответа)
– Добавьте новое поле во все методы, связанные с заявкой: на создание заявки, редактирование, получение
– Опишите новый параметр запроса по шаблону (название параметра, тип данных, обязательность, описание с учетом валидации)
– Опишите специфичную бизнес-логику, если она есть

🔷 Опишите сценарии взаимодействия
– В какой момент фронт будет запрашивать справочник?
– Что делать на фронте, если справочник не удалось получить (вернулась ошибка)?
– Кешируем ли справочник на фронте? На сколько?
– Если описываете, какие методы вызывает фронт и с какими параметрами, то обязательно уточните, как используется новое поле в запросах и ответах.

🔷 Изменения в БД
Как правило, все поля БД описываются в виде таблицы. В эту таблицу нужно внести новое поле:
– Найдите таблицу, куда добавите новое поле
– Название поля
– Тип данных
– Обязательность
– Описание (с учетом валидации)

🔷 Доработка сервиса принятия решений (если цель влияет)
– Влияет ли цель на ставку, срок, решение?
– Какие значения влияют и как?
– Обновите описание скоринга
– Кто согласует изменения логики?

🔷 Задача на миграцию. Обработка старых заявок
– Что делать с уже созданными заявками без цели?
– Какие значения подставлять?
– Если делаем маппинг — по каким правилам?
– Можно выгрузить заявки, вручную проставить цели в Excel и передать разработчику — он напишет миграцию
– Укажите, что миграция отображается в истории изменений от имени системного пользователя

🔷 Изменения для отчётности / BI
– В какие отчёты и выгрузки нужно добавить поле
– В каком месте появится новое поле
– Опишите поле
– Опишите цели использования поля

🔷 Для менеджера и всей команды
Напишите:
– Открытые вопросы и риски
– Что можно вынести вне MVP
– Места, где потребуется отдельное согласование и кого именно

💡 Как видите, простая задача оказалась не такой простой. B работе системного аналитика так всегда. Но вы и сами наверняка с этим сталкивались 🙂.


Если разбор понравился, ставьте реакции ❤️‍🔥, так мы узнаем, интересно ли это вам.

#requirements #тз_разбор