💡 Хотите понять, чем занимается системный аналитик в разных компаниях? У нас есть бесплатный урок!

В нём:
🔹 Что делает системный аналитик в разработке ПО.
🔹 Разбор реальной рабочей задачи: «что и в каком виде приходит от заказчика» и «как системный аналитик с этим работает».
🔹 Возможность оценить нашу подачу материала и формат обучения.

Попробуйте бесплатно!
Успейте записаться, места ограничены.

Мы готовим курс по документации и хотим, чтобы он был по-настоящему полезным 🙌

В нём будет про то, как оформлять пространство в Confluence, как связывать задачи в Jira с документацией и как писать ТЗ так, чтобы оно сразу становилось документацией по продукту.
Будем делиться шаблонами, примерами, лайфхаками — всё как вы любите 😉

Но чтобы курс точно решал актуальные задачи, нам НУЖНА ВАША ПОМОЩЬ!
Расскажите, какие вопросы про документацию вас волнуют — и мы постараемся включить их в программу.

👉 Заполните короткий опрос (2–3 минуты) https://forms.gle/viFWmF5VVmdtApix9
А мы пришлём вам скидку на курс, когда он запустится!

Будем рады вашим идеям 🙌

В ближайшие недели мы будем говорить об API — в особенности про REST API 🔥

Сегодня API встречается в каждом проекте — и понимание, как он устроен, критически важно для работы системного аналитика.

📌 Нужно продумать взаимодействие между фронтом и бэком в вашей системе? Используете API.
📌 Нужно интегрироваться с другой системой в вашей компании? Снова API.
📌 Нужно подключиться к внешнему сервису, чтобы подтянуть адреса, курсы валют? Без API никуда.

Системному аналитику важно:
— понимать, что такое API и как он работает,
— уметь тестировать API в целях анализа,
— уметь проектировать API, т. к. в текущих реалиях во многих командах эту работу возложили на системного аналитика.

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

Оставайтесь с нами и следите за постами — будет полезно и практично! 💪

🤔 Что такое API простыми словами?

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

Магазину нужно передавать сервису доставки информацию о заказах, адресах и контактах клиентов. Но эти системы говорят на «разных языках». Как же им взаимодействовать?

💡 Вот здесь на помощь приходит API — интерфейс, который помогает системам обмениваться информацией по заранее определённым правилам.

Можно представить API как официанта в ресторане:

🍽️ Клиент (первая система) не ходит на кухню (вторая система) за своим заказом, а просит официанта (API).
🍽️ Официант знает меню (набор запросов и данных), принимает заказы и приносит именно то, что клиент попросил.
🍽️ Кухня не видит клиента, она просто готовит блюда по заказам, которые передал официант.

Таким образом, API позволяет двум системам общаться, не «видя» внутреннего устройства друг друга.

Ещё несколько примеров API:
📍 Карты — приложение такси через API получает координаты и маршруты из Яндекс.Карт или Google Maps.
💱 Курсы валют — сайт туристического агентства получает через API актуальные курсы валют от ЦБ.
🌦️ Прогноз погоды — приложение погоды через API запрашивает данные у крупных метеосервисов.

#api

API — это какой вид интеграций?

Всех системных аналитиков рано или поздно спрашивают на собеседованиях:
«Какие виды интеграций знаешь?» 🤔

Обычно хотят услышать эти 4 вида:

1️⃣ Общая база данных

Несколько систем напрямую взаимодействуют с одной и той же базой данных.
Обычно одна из систем владеет схемой и данными, а другие — получают доступ только для чтения.
📌 Пример: система хранит данные заказов в своей БД, и предоставляет «представление» (view) с нужными полями. Сервис аналитики (например, Power BI) подключается к этой базе, читает данные из view и строит отчёты.
Это простой и быстрый способ интеграции, но с высокой связностью и рисками.

2️⃣ Обмен файлами

Системы обмениваются данными в виде файлов — CSV, XML, Excel, изображения и т. д.
Это классический способ интеграции, когда одна система пишет файл, а другая — читает.
📌 Пример: банк выгружает транзакции в CSV и передаёт их в налоговую через защищённый канал.
📌 Пример: изображения, загруженные пользователями на сайт, сохраняются в хранилище (например, S3), а другой сервис или сайт читает оттуда файлы и отображает их на страницах.
Это тоже интеграция — через общий доступ к файлам, без прямых запросов между системами.

3️⃣ Удалённый вызов процедур (RPC)
Это когда одна система напрямую вызывает метод или процедуру другой системы, как будто это её собственная процедура.
Примеры:
SOAP
gRPC
*REST API
*GraphQL

4️⃣ Обмен сообщениями (Message queue)
Одна система отправляет сообщения в очередь, а другая забирает их оттуда и обрабатывает по очереди. Примеры: Kafka, RabbitMQ, ActiveMQ, IBM MQ.

❗Такие API, как SOAP, gRPC реализуют подход удалённого вызова процедур (RPC) — когда одна система вызывает функцию другой, как будто она локальная.
REST и GraphQL не относятся к RPC в строгом смысле, но тоже позволяют обращаться к удалённой логике — просто делают это по другим архитектурным принципам.

💡 В следующих постах поговорим о паттерне «запрос — ответ»: чем он хорош, где его пределы и почему он лежит в основе большинства API-интеграций.
Разберём, как его реализуют REST, gRPC и другие подходы.

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

#api #interview

📢 Напоминаем: совсем скоро старт потока!

Курс «Системный аналитик. С нуля до старта» становится только сильнее💪.
В этот поток мы добавили новый модуль про интеграции — разбираем виды интеграций и в особенности REST API.
Также в курс вошёл карьерный модуль. В нём делимся частыми вопросами с собеседований (в том числе по API и интеграциям) и даём рекомендации по оформлению резюме.

В AnalystCore мы подстраиваем программу под вас:
выясняем, с каким уровнем вы пришли, и помогаем дойти до вашей цели.
Отвечаем на все вопросы, разбираем ДЗ лично, поддерживаем и помогаем.

🎯 Через 4 месяца вы:
— разложите знания по полочкам,
— будете уверенно говорить про REST API,
— и сможете повысить грейд и зарплату.

⚡️ Успейте записаться.
Начните сейчас — и к осени вы уже будете совсем на другом уровне.

👉 Подробности и запись на курс: https://analystcore.com/system-analyst-base

📬 Что такое модель «запрос–ответ» и как с ней работают системы?

Когда две системы обмениваются данными, чаще всего это происходит по принципу «запрос–ответ».
Это базовый паттерн, который лежит в основе REST API, GraphQL, gRPC и других форматов взаимодействия.

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

Одна система (клиент) отправляет запрос. Например:
«Дай список заказов пользователя с ID 123».

Вторая система (сервер) обрабатывает запрос и отправляет ответ. Например:
«Вот список заказов. Их три: заказ от 1 апреля, заказ от 3 апреля, заказ от 7 апреля».

📌 Что обычно содержит запрос?
— Метод запроса (например, GET, POST, PUT, DELETE — о них расскажем в одном из следующих постов)
— Адрес запроса (например, /users/123/orders)
— Заголовки (например, информация об авторизации, формате данных и др.)
— Тело запроса (body) — не всегда, но если нужно передать данные (например, при создании нового заказа)

📦 Что возвращается в ответе?
— Код ответа (например, 200 — всё ок, 404 — не найдено, 500 — ошибка сервера)
— Заголовки ответа (доп. информация, например, о типе возвращаемого контента)
— Тело ответа — сами данные, которые система вернула. Они могут быть отправлены в формате JSON, XML и т. д.

Это основа, с которой стоит начинать разбираться в API.
А дальше мы постепенно пойдём к REST — одному из самых популярных способов взаимодействия между системами.

В следующем посте расскажем, почему REST стал таким популярным и чем он отличается от других подходов. Не пропустите.

#api

📬 Что такое HTTP — и при чём тут REST?

Прежде чем разбираться с REST API, давайте поймём, на чём он работает.

💡 HTTP (HyperText Transfer Protocol) — это протокол передачи данных, на котором работает весь интернет.
Когда вы открываете сайт, отправляете форму или оформляете заказ — вы используете HTTP.

👉 REST работает поверх HTTP. Он просто использует его возможности — грамотно и системно.

📦 А теперь представьте, что вы отправляете обычное письмо:
— У вас есть конверт — это как тело запроса: в нём содержится информация, которую вы хотите передать.
— Вы указываете адрес получателя — это как URL, по которому нужно доставить сообщение.
— Клеите марку, где указано, что именно вы хотите сделать: получить, отправить, удалить, обновить. Это как метод запроса: GET, POST, PUT, DELETE.

📮 А дальше — всё как на почте: письмо отправляется, доходит до адресата, и если всё прошло хорошо — вы получаете ответ.

💡 HTTP — это та самая «почтовая служба».
А REST — это стиль, в котором мы этой службой пользуемся: аккуратно, понятно и по правилам.

Теперь вы готовы начать разбираться с REST. Ждите продолжение!

#api #http #rest

📦 REST — это не технология, это архитектурный стиль

Когда речь заходит об API, чаще всего упоминают именно REST. Он стал стандартом, и его часто требуют в вакансиях. Но почему?

💡 REST (Representational State Transfer) — это архитектурный стиль, основанный на использовании стандартных возможностей HTTP.
REST — это набор принципов, который говорит:
«Если вы делаете API — делайте его по-человечески, чтобы все его поняли».

Например, в HTTP есть стандартные методы:
GET, POST, PUT, DELETE.

REST предлагает:
🔹 GET — использовать, чтобы получить данные,
🔹 POST — создать новую сущность,
🔹 PUT — обновить существующую,
🔹 DELETE — удалить.

✨ Сами по себе эти методы может использовать и gRPC, и SOAP, и что угодно.
Но REST говорит: давайте договоримся, что POST — это не для удаления, а GET — не для обновления. Используем каждый метод по назначению.
То есть REST — это не просто способ общения между системами, а понятный стиль взаимодействия, в котором:
— поведение методов предсказуемо,
— код читается легко,
— API интуитивно понятно всем.

📌 REST использует коды ответа и другие элементы HTTP по назначению. Это не обязательно (с технической точки зрения), но именно договорённость и делает REST таким удобным и универсальным.

👉 В следующем посте разберём, как читается путь запроса в REST: что такое endpoint, ресурс, параметры — и как в этом всём не запутаться.

Следите за серией, дальше — практика!

#api #rest

📌 Что такое endpoint и ресурс в REST API?

Когда вы видите такой путь:
/users
это не просто адрес. Это — ресурс.

🔹 Ресурс — это сущность, с которой работает ваша система: пользователи, заказы, товары, документы.
🔹 Endpoint — это конкретный URL, по которому можно получить доступ к ресурсу через API.
В REST API мы не придумываем названия ручек вроде /getAllUsers или /createOrder.
Мы описываем что, а действие определяем через метод HTTP-запроса:

GET /users — получить список пользователей
POST /users — создать нового пользователя
GET /users/123 — получить пользователя с id 123
PUT /users/123 — полностью обновить пользователя
PATCH /users/123 — частично обновить данные пользователя
DELETE /users/123 — удалить пользователя

✨ Это и есть суть REST — использовать HTTP как язык общения, а URL — как «адрес объекта».
Такой подход делает API понятным, предсказуемым и удобным — и вам, и разработчикам, и тестировщикам.
В следующем посте расскажем, зачем в пути появляются цифры и как работают path-параметры.
Следите за серией!

#rest #api

🔢 Зачем в пути цифры? Как работают path-параметры в REST API

В прошлом посте мы говорили, что путь в REST API — это адрес ресурса.
Но что делать, если нужно обратиться не ко всем, а к конкретному ресурсу?
📌 Для этого используются path-параметры (или параметры пути).

Пример:
GET /users/123 — получить пользователя с ID 123
DELETE /orders/555 — удалить заказ с ID 555
PATCH /products/8 — частично обновить товар с ID 8

Цифра в пути — это path-параметр.
Он указывает, с каким именно экземпляром ресурса вы хотите работать.

🔗 А если нужно обратиться к вложенному ресурсу?
Всё по той же логике:
GET /users/123/orders — все заказы пользователя с ID 123
GET /users/123/orders/456 — конкретный заказ 456 этого пользователя

Такой подход отражает иерархию ресурсов. Даже по самому URL можно понять, с какими данными работает запрос, и как они связаны между собой.

#rest #api

🔎 Что такое query-параметры и зачем они нужны в API?

Если path-параметры помогают указать, какой именно объект нас интересует,
то query-параметры (параметры запроса) нужны для того, чтобы управлять выборкой данных.

📍 Пример запроса с query-параметрами:
GET /orders?from=2024-01-01&to=2024-04-17&status=paid
Это означает:
— показать заказы с 1 января по 17 апреля
— только со статусом «оплачен»
Такие параметры идут после знака ? и перечисляются через &.

Что обычно передаётся в query-параметрах:
🔹 Фильтры
/products?category=books&price_lte=1000 — только книги до 1000 ₽
🔹 Сортировка
/orders?sort=date_desc — отсортировать заказы по дате, от новых к старым
🔹 Пагинация (разбиение на страницы)
/users?page=2&limit=10 — вторая страница, по 10 пользователей на страницу
🔹 Поиск
/articles?search=REST%20API — найти статьи по ключевым словам

💡 Почему query-параметры не указывают прямо в пути?
Потому что они не обязательны. Это опции, которые уточняют, что именно нам нужно.
А путь (/orders) остаётся неизменным — мы всё ещё обращаемся к коллекции заказов.

⚠️ Главное правило:
— Если мы обращаемся к объекту — используем path-параметр
— Если хотим повлиять на выборку — используем query-параметры

#rest #api

🚧 Что в путь, а что в параметры?

Когда вы проектируете REST API, один из частых вопросов:
какую информацию указывать в path, а что — в query? 🤔

Чтобы API был логичным и удобным, важно соблюдать этот принцип:
📌 Path-параметры (/users/123)
— Обязательные
— Указывают на конкретный ресурс или путь к нему
— Влияют на маршрут
— Без них запрос не имеет смысла

📌 Query-параметры (?sort=date&limit=10)
— Необязательные
— Управляют выборкой или поведением запроса
— Не меняют маршрут
— Можно убрать, и запрос всё равно сработает

#rest #api

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

❌ /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