Почему сотрудники плохо работают: новый взгляд на бизнес-процессы

⏳ 6 мин | 🟤⚪️⚪️

Перейти | BA|SA

AI в работе технического писателя

⏳ 4 мин | 🟤🟤⚪️

Перейти | BA|SA

BPMN умер, все сделает ИИ

⏳ 4 мин | 🟤⚪️⚪️

Перейти | BA|SA

Кто выполняет функции системного аналитика в США?

⏳ 6 мин | 🟤⚪️⚪️

Перейти | BA|SA

Документирование API сервисов с помощью Swagger на примере фреймворков Express.js и Gin

⏳ 41 мин | 🟤🟤⚪️

Перейти | BA|SA

От монолита к микросервисам. Монолитная модель данных. Распознать и обезвредить

⏳ 5 мин | 🟤🟤⚪️

Перейти | BA|SA

Нужно ли системному аналитику разбираться в программировании?

⏳ 19 мин | 🟤⚪️⚪️

Перейти | BA|SA

Как провести бенчмарк кластера Camunda 8

⏳ 10 мин | 🟤🟤⚪️

Перейти | BA|SA

Как не скатиться в имитацию: о роли системного аналитика на проекте

⏳ 7 мин | 🟤🟤⚪️

Перейти | BA|SA

Салют! Сегодня продолжим тему документации API, и я немного расскажу, что делаю я))

Для начала, пару слов из общего понимания, хорошая документация API — это не просто справочник по методам, а инструкция для разработчика, которая экономит время и снижает количество ошибок. Но не все аналитики с ней работают, у меня были проекты, где был отдельный человек на эту работы😊

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

📌 Из чего состоит моя документация API?

1️⃣ Обзор (Overview)

- Для чего этот API? (например, "Платежный шлюз для обработки транзакций").
- Ключевые возможности (например, "Создание платежа, проверка статуса, возврат средств").
- Форматы данных (JSON/XML, кодировка).
- Базовый URL (`https://api.example.com/v1`).

📌 Совет: Добавьте диаграмму взаимодействия, если API сложный (например, схему работы OAuth).

2️⃣ Аутентификация и авторизация

- Как получить токен/ключ?
- Где его передавать (`Header`, Query, `Body`)?
- Пример запроса:

   curl -X POST https://api.example.com/auth \
    -H "Content-Type: application/json" \
    -d '{"api_key": "your_key"}'  
    

- Срок жизни токена, refresh-токены (если есть).

📌 Совет: Добавьте ссылку на генератор тестовых ключей (если есть Sandbox).

3️⃣ Эндпоинты (Endpoints)

Каждый метод описываю по шаблону:
🔹 Метод `GET /users`
- Назначение: Получение списка пользователей.
- Параметры:
- limit (макс. количество записей, по умолчанию 20).
- offset (пагинация).
- Заголовки:
- Authorization: Bearer <token>.
- Пример запроса:

   curl -X GET "https://api.example.com/users?limit=10" \
    -H "Authorization: Bearer YOUR_TOKEN"  
    

- Пример ответа:

   {
    "data": [
      {"id": 1, "name": "Alice"},
      {"id": 2, "name": "Bob"}
    ],
    "total": 2
  }  
    

- Возможные ошибки:
- 401 Unauthorized — неверный токен.
- 400 Bad Request — некорректные параметры.

📌 Совет:
- Группируйте методы по логическим блокам (например, Users, Orders, `Payments`).
- Для неочевидных параметров добавьте пояснение (например, amount в **копейках**).

4️⃣ Примеры кода

Добавляю готовые сниппеты для разных языков:
- cURL (для быстрого тестирования).
- Python (`requests`).
- JavaScript (`fetch`/`axios`).
- PHP, Java (если аудитория использует).

📌 Совет: Используйте Swagger Codegen или Postman Snippets для автоматической генерации.

5️⃣ Обработка ошибок

Отдельный раздел с:
- HTTP-кодами (4xx, 5xx).
- Типовыми ошибками и способами их исправить.
- Примером ошибки:

   {
    "error": "invalid_request",
    "message": "API key is missing",
    "details": "Add 'Authorization: Bearer YOUR_KEY' header"
  }  
    

📌 Совет: Добавьте ссылку на сервис мониторинга (если есть, например, статус-страницу API).

6️⃣ Вебхуки (Webhooks)

Если API отправляет события:
- Какие события есть (например, payment.success, `order.canceled`).
- Как настроить URL для вебхуков.
- Пример payload:

   {
    "event": "payment.success",
    "data": {"id": "123", "amount": 1000}
  }  
    

- Рекомендации:
- Всегда проверяйте подпись (если есть).
- Idempotency-ключи для избежания дублей.

📌 Совет: Добавьте инструкцию по тестированию вебхуков (например, через ngrok или локальный тунель).

7️⃣ Лимиты и ограничения

- Rate limiting (например, 100 запросов/минуту).
- Максимальный размер запроса (например, 10 MB для `POST`).
- Ограничения на поля (например, description не больше 500 символов).

📌 Совет: Укажите, как проверить текущий лимит (например, через заголовки X-RateLimit-Limit и `X-RateLimit-Remaining`).

8️⃣ Чейнджлог (Change Log)

- Версии API и даты изменений.
- Breaking changes (например, удаление поля created_at в v2).
- План по депрекейшену старых версий.

📌 Совет: Используйте семантическое версионирование** (`v1.0.0` → `v1.1.0`).

P.s. Я на двух проектах сталкивалась с документированием API, и там и там использовала одно и тоже содержание, но где-то что-то отличалось, но суть была одна!

Источник: @ba_and_sa

Паттерны кеширования: проблемы, решения, практические рекомендации

⏳ 14 мин | 🟤🟤⚪️

Перейти | BA|SA

Obsidian для профессионалов: рабочая система заметок на стыке подходов

⏳ 7 мин | 🟤🟤⚪️

Перейти | BA|SA

Салют! Любой Аналитик (БА или СА) может столкнуться с Базами данных (БД), в любом случае это любимые вопросы на собесах. Поэтому предлагаю эту тему тоже не оставлять в стороне)

#БД #базыданных

1️⃣ Основные понятия

База данных (БД) – это структурированный набор данных, организованный для удобного хранения, управления и доступа.

Ключевые термины:
- Таблица (Table) – структура для хранения данных в виде строк (записей) и столбцов (полей).
- Запись (Row, Record) – строка в таблице, содержащая данные об одном объекте.
- Поле (Column, Field) – столбец в таблице, определяющий тип данных (например, имя, `возраст`).
- Первичный ключ (Primary Key, PK) – уникальный идентификатор записи (например, `id`).
- Внешний ключ (Foreign Key, FK) – поле, связывающее таблицы между собой.
- Индекс (Index) – структура для ускорения поиска данных (как оглавление в книге).
- Нормализация – процесс устранения дублирования данных для улучшения структуры БД.

2️⃣ Разница между БД и СУБД

БД (База данных) — это просто хранилище информации, как цифровая "коробка с данными".

СУБД (Система управления базами данных) — это "умная программа", которая:
- Организует хранение данных в БД,
- Быстро находит и изменяет информацию,
- Защищает данные от ошибок и несанкционированного доступа,
- Позволяет удобно работать с БД через запросы (например, SQL).

Проще:
- БД — это как файл Excel (там лежат данные).
- СУБД — это как сам Excel (он умеет сортировать, фильтровать и защищать эти данные).

Без СУБД БД — просто беспорядочная куча информации. СУБД делает её удобной и рабочей

Аналогия:
- БД – это библиотека с книгами (данными).
- СУБД – это библиотекарь, который ищет, добавляет и изменяет книги.

3️⃣ Реляционные vs Нереляционные БД

Реляционные БД (SQL)

- Структура: Таблицы с жесткой схемой (строгие типы данных).

- Примеры: MySQL, PostgreSQL, Oracle, SQL Server.

- Плюсы:
- Четкая структура и связи (FK).
- Поддержка транзакций (ACID).
- Удобны для сложных запросов (`JOIN`, агрегации).

- Минусы:
- Менее гибкие (схему сложно изменить).
- Могут быть медленными при больших объемах.

Нереляционные БД (NoSQL)

- Структура: Документы, ключ-значение, графы, колоночные хранилища.

- Примеры: MongoDB (документы), Redis (ключ-значение), Cassandra (колоночная).

- Плюсы:
- Гибкость (данные могут быть без строгой схемы).
- Высокая производительность и масштабируемость.

- Минусы:
- Нет стандартных JOIN (связи сложнее).
- Меньше гарантий целостности данных.

Когда что выбирать?
- SQL – если важны транзакции, сложные запросы, строгая структура (банки, ERP).

- NoSQL – если нужна масштабируемость и гибкость (соцсети, IoT, big data).

4️⃣ Что должен знать начинающий системный аналитик про БД?

1. Умение читать схемы БД (ER-диаграммы).
2. Базовый SQL (`SELECT`, JOIN, `GROUP BY`).
3. Понимание нормальных форм (1NF, 2NF, 3NF).
4. Различие типов БД и их применение.
5. Как данные связаны между собой (один-ко-многим, многие-ко-многим).
6. Основы индексов (зачем нужны и как влияют на производительность).

Вместо вывоводов:

БД – основа почти любой информационной системы. Системный аналитик должен понимать, как данные хранятся и взаимодействуют, чтобы проектировать корректные требования и общаться с разработчиками.

🔥 Совет: Попробуйте создать простую БД (например, в SQLite или PostgreSQL) и потренируйтесь в SQL – это лучший способ разобраться!

В след раз углубимся в тему 😉