🤔Каково быть системным аналитиком?
Мир IT всегда был для меня местом, где встречаются технологии, искусство и бизнес. И именно в роли системного аналитика я однажды нашла свое место.

Каждый день мне предстоит узнавать что-то новое. От тонкостей бизнес-процессов до технических решений от архитекторов и разработчиков. Каждый проект, каждый человек в команде, учит видеть мир шире.

У меня есть опыт в проектной и в продуктовой разработке. Благодаря этому я получила много бытовых знаний из разных предметных областей: как устроены процессы в торговле и производстве, как работают агрегаторы билетов, банки и прием платежей на сайте доставке еды, и другие. Этот опыт не только разнообразил мой профессиональный рост, но и позволил по-новому взглянуть на привычные вещи. Некоторые хитрости применяю в повседневной жизни, за пределами работы. Смогу помочь открыть любой из бизнесов, с которыми уже работала, так как знаю внутреннюю кухню.
*Из грустного: много конфиденциальной информации и крутых решений, которые нельзя раскрывать.

В роли системного аналитика я не просто пишу требования к системам. Я помогаю создавать и развивать бизнес за счет автоматизации.

Меня всегда привлекало быть лидером. Поэтому мои обязанности никогда не ограничивались только аналитикой. На позиции системного аналитика есть возможность проявить себя в роли лидера: управлять командами и стать надежным партнером для всех сторон проекта.

🌟 А возможность работы из любой точки мира - это отдельная часть удовольствия от рабочих процессов!

🌱 Я убеждена, что в мире IT нет предела совершенству. Каждый новый проект, каждая задача – это шанс стать лучшей версией себя.

Я выбрала не просто профессию системного аналитика. Я выбрала путь постоянного самосовершенствования, открытий и радости от результатов 🙌

📋 Задачи системного аналитика при проектировании REST API:

1. Сделать описание метод - что это и для чего.
2. Описать логику его работы - алгоритм.
3. Определить формат запросов и ответов, влияние на БД.

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

⬇️⬇️⬇️⬇️⬇️

🔵 Функциональные требования к проекту TMS

Управление задачами:
▫️Создание новой задачи: Пользователь должен иметь возможность создать новую задачу, указав её описание, приоритет, срок исполнения и другие необходимые параметры.
▫️Создание комментария к задаче: Пользователь может добавить комментарий к определенной задаче, описывая ход выполнения, проблемы или другие замечания.
▫️Изменение статуса задачи: Пользователь может менять статус задачи (например, "в работе", "завершено", "отложено").
▫️Изменение приоритета задачи: Пользователь может изменить приоритет задачи в зависимости от её актуальности.

Взаимодействие с пользователями:
▫️Получение списка всех задач: Пользователи могут просматривать общий список задач, чтобы понимать общий объем работы.
▫️Получение списка задач определённого пользователя: Любой пользователь может просмотреть список задач, назначенных конкретному коллеге.
▫️Получение деталей конкретной задачи: Пользователь должен иметь возможность увидеть все детали задачи, включая её статус, исполнителя и историю изменений.
▫️Получение деталей конкретного пользователя: Позволяет узнать общую информацию о пользователе, а также его активные и завершенные задачи.

Стоит отметить, что функциональность Task Management System (TMS) может быть гораздо шире, и это лишь малая часть методов, которые могут быть реализованы в реальной системе.

Таким образом, наша система предоставляет набор базовых операций для управления задачами и взаимодействия с пользователями. В следующих постах мы будем проектировать конкретные методы REST API для реализации этих функций.

📌POST в REST API

Один из основных HTTP-методов, используемых в REST - это POST.

HTTP-метод POST в контексте REST API обычно используется для создания новой записи в БД. Это может быть, например, новый товар в интернет-магазине, новый комментарий на веб-сайте или новый пользователь при регистрации в системе.


Когда используется POST?

🟢 Необходимо добавить новую запись, создать данные в БД.
🟢 Сервер должен сгенерировать уникальный идентификатор (ID) этой новой записи.


Когда НЕ рекомендуется использовать POST?

❌Для чтения данных:
POST не должен использоваться, если вы просто хотите извлечь данные, не внося при этом изменений. Для этого лучше использовать метод GET.

❌Для обновления существующих ресурсов:
Если вы хотите изменить уже существующий ресурс, лучше использовать метод PUT (если заменяете ресурс полностью) или PATCH (если частично обновляете данные ресурса).

❌Для удаления ресурсов (данных из БД):
Для этой цели существует специальный метод DELETE.

❌Когда идемпотентность важна:
POST не является идемпотентным методом, что означает, что повторное выполнение одного и того же запроса POST может привести к различным результатам. Если вам важно, чтобы операция могла быть безопасно повторена многократно, рассмотрите использование идемпотентного метода PUT.

Основные рекомендации при выборе POST:


🌟 Метод POST создает одну или несколько записей в БД, в зависимости от переданного тела запроса (JSON/XML/...) - один объект или массив (список объектов).

POST https://tms.com/api/v1/tasks или POST https://tms.com/api/v1/task - создать задачу.
POST https://tms.com/api/v1/user - зарегистрировать пользователя.
POST https://tms.com/api/v1/user/{userId}/task - создать задачу для пользователя с идентификатором {userId}*.



🌟 Метод POST используется, когда id записи при ее создании в БД генерируется на сервере.

POST https://tms.com/api/v1/task/{taskId} - создать задачу и присвоить ей id в БД со значением {taskId}*. Не рекомендуется так делать, т.к. id генерируется на клиенте. Лучше PUT, а не POST.

*{userId} и {taskId} - указатели на конкретные объекты данных в БД по их уникальным id.
Пример для id задачи = 123: POST https://tms.com/api/v1/task/123.



🌟 Тело запроса POST обычно содержит данные для создания новой записи в формате JSON или XML (+ другие форматы). Но это не обязательно. Данные также могут быть переданы в query-параметрах, headers или просто не требоваться при создании записи в БД (например, при авто-генерации данных на сервере).

POST https://tms.com/api/v1/task?name=Документирование - создать задачу с названием “Документирование”, name - query-параметр. Лучше все же это отправлять в Body, т.к. название может быть длинным и влиять на длину URL.




🌟 При успешном выполнении POST-запроса возвращается статус 201 (Created) с информацией о созданной записи. Информацию о созданной записи возвращать не обязательно. Можно вернуть пустое тело ответа.


Эти детали стоит помнить и проверять себя каждый раз при проектировании API 💻

📌JSON и его взаимосвязь с базами данных

Одним из ключевых форматов, используемых для представления и передачи данных, является JSON. Что это такое и какова его связь с базами данных? Давайте разберемся.

JSON, что расшифровывается как "JavaScript Object Notation", является легковесным форматом данных, который легко читается и пишется как человеком, так и системами. Он основан на синтаксисе объекта языка программирования JavaScript, но существует независимо от языка.

Пример данных в формате JSON:
{
"name": "Алексей",
"age": 30,
"isStudent": false,
"hobbies": ["футбол", "путешествия"]
}

В этом примере у нас есть:

🔹Объект {} человека или пользователя, в зависимости от контекста системы. Всегда есть открывающаяся и закрывающаяся скобка.

🔹Пары ключ-значение: слева в кавычках указывается название поля, а справа его значение. Что важно, название полей в JSON и в БД не обязательно совпадают.

🔹Показаны возможные типы данных: обратите внимание, что числа без кавычек, массивы (списки однотипных данных) в [], boolean - флаги да/нет (true/false) также без кавычек.

🔹camelCase - рекомендация по именованию полей.



🔗 Зависимость от БД

Когда мы говорим о "зависимости" JSON от базы данных, важно понимать, что сам по себе JSON является независимым форматом. Однако способ, каким БД обрабатывает, хранит и индексирует JSON-данные, может существенно влиять на производительность и возможности вашей системы.

Есть определенные лайфхаки по построению JSON-объектов на основе связанных в БД таблицах, которые помогают не потерять важные данные, которые надо вернуть или отправить в API.

JSON - стандарт в мире программирования и обработки данных. Он позволяет системам обмениваться структурированной в едином стиле информацией.


Для работы с JSON и самостоятельных экспериментов рекомендую: https://jsoneditoronline.com/
С помощью этого инструмента можно проверять себя, правильно ли вы строите объекты данных JSON.

Итак, спорный вопрос, за который спасибо коллегам в чате. Решила поискать что там у нас в мировых компаниях и нашла интересную информацию.

В именовании ресурсов в REST API есть разные подходы, и, честно говоря, нет строгого стандарта.

Однако на практике чаще всего предпочитают использовать единственное число для ресурсов. Но и множественное число также активно используется!

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

Примеры:

Единственное число:
GET /task/123 - получить информацию о задаче с ID 123.
POST /task - создать новую задачу.

Множественное число:
GET /tasks - получить список всех задач
GET /tasks/123 - получить информацию о задаче с ID 123.
POST /tasks - создать новую задачу.


Множественное число представляет собой коллекцию элементов, что соответствует идеологии REST для метода добавления нового элемента в коллекцию и чтения списка - /tasks читается легче, где у вас есть коллекция ресурсов и конкретные ресурсы внутри этой коллекции.



🔍 Рекомендации по множественному числу есть в гайдлайнах:

Microsoft API Guidelines
7.4.1. POST ---> POST http://api.contoso.com/account1/servers

Google Cloud API Design Guide
Resource names ---> Example 1: A storage service has a collection of buckets, where each bucket has a collection of objects



Продолжение.... ⬇️⬇️⬇️

😰 При этом, если мы взглянем на Яндекс:

Пример с ед. числом:
https://yandex.ru/dev/rasp/doc/ru/reference/nearest-settlement
Пример с мн. числом:
https://yandex.ru/dev/market/partner-api/doc/ru/overview/express

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


Помимо этих источников, хорошей практикой также является изучение и анализ популярных публичных API, чтобы увидеть общепринятые стандарты в сообществе. А лучшая практика - посмотрите как у вас уже реализован API в компании!

‼️ Важно помнить ‼️
Вне зависимости от выбранного подхода, ключевым является его последовательное использование на протяжении всего проекта API.


‼️ Договариваемся на этот проект ‼️
Делаем как Microsoft и Google и в нашем проекте Task Management System будем использовать множественное число.
GET /tasks
GET /tasks/123
POST /tasks

P.S. Хотя я предпочитаю единственное число, для меня важнее договоренность с командой и поддержка единого подхода на протяжении всего проекта 🔑

🚒 Борьба со страхами 🚒

В каждом специалисте, будь то системный аналитик или кто-либо другой, скрываются страхи, мешающие развиваться и двигаться вперёд. Но познав их, можно преодолеть и стать лучшей версией себя!

🔍 Топ-5 страхов аналитика:

1️⃣ Страх ошибиться. "А что, если мое решение по проекту окажется неверным?" - наверняка все мы хоть раз задавались этим вопросом.

2️⃣ Страх критики. Особенно от коллег или начальства. "А что, если меня не поймут или осудят, особенно за ошибки?". "Лучше оставлю своё мнение при себе, хотя знаю, что коллеги не правы и можно попробовать подойти к решению задачи по другому. Вдруг я ошибаюсь?".

3️⃣ Страх устаревания знаний. Мир IT быстро меняется, и всегда есть риск остаться позади, если не успеваешь осваивать новое.

4️⃣ Страх ответственности. Боязнь нести ответственность за проект или принятое решение.

5️⃣ Страх несовершенства. Постоянное желание сделать все идеально может замедлить процесс работы.


💡 Как преодолеть эти страхи?

👇👇👇

💡Как преодолеть страхи?

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

2️⃣ Помните о конструктивной критике. Если критика объективна и по делу, это поможет вам стать лучше. Примите её с благодарностью. В ином случае советую задуматься о том, а правильный ли коллектив вас окружает? Может пора менять компанию?

3️⃣ Постоянное самообучение. Поддерживайте актуальность своих знаний, посещая курсы, воркшопы и читая профессиональные статьи и литературу.

4️⃣ Сотрудничайте. Вы не одни! Работайте в команде, советуйтесь с коллегами, и вместе вы сможете добиться лучших результатов проектирования, а также перенять их опыт. Одна голова хорошо, 2+ лучше.

5️⃣ Идеальное — враг хорошего. Совершенство не всегда необходимо. Иногда не стоит бояться показывать промежуточные решения, чтобы опять же - получить обратную связь от коллег.


Каждый день, преодолевая свои страхи, вы делаете шаг к своему совершенству.
Помните, что смелость - это не отсутствие страха, а способность действовать, несмотря на него 💪

📌Пример POST в REST API: Проектирование метода REST API "Создание новой задачи"

🟢 Описание метода:

Метод предназначен для создания новой задачи в системе TMS (Task Manager System). Метод позволит пользователям добавлять новые задачи и задавать начальную информацию о них.


🟢 Логика работы:

При получении запроса POST запроса на создание задачи от клиента REST API TMS на сервере (backend) должны быть выполнены следующие действия:

1. Сервер проверяет корректность данных, полученных в теле запроса Body (JSON) с описанием задачи.

2. Если данные корректны, создается новая запись в базе данных. Ей присваивается уникальный идентификатор id в формате UUID.
Если статус задачи не был передан в запросе, то по умолчанию установить значение “open”.
Все поля, которые не были переданы для создания задачи, указать значение null.

3. Сервер возвращает успешный ответ с данными о созданной задаче.

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


Обработка ошибок:

1а. Если не указано название задачи, то вернуть… .

1б. И т.д. - список требований к обработке ошибок.

-----------------------------
👇👇👇

🟢 Формат запросов и ответов:

Запрос:
POST /https://tms.com/api/v1/tasks
*Договариваемся, что у нас эндпоинты в мн. числе.

Content-Type: application/json
Body:
{
"name": "Задача №1",
"description": "Описание задачи",
"dueDate": "2023-11-01",
"priority": "high"
}


Успешный ответ:

HTTP-201 Created
Content-Type: application/json
{
"id": 123,
"name": "Задача №1",
"description": "Описание задачи",
"dueDate": "2023-11-01",
"priority": "high",
"status": "open",
"createdAt": "2023-10-16T10:00:00Z"
}

Обработка ошибок:

1. Не передано название задачи.
HTTP-400
Content-Type: application/json
{
"message": “Задача не может быть создана. Укажите название задачи”,
“field”: “name”
}

2. …



В результате успешного выполнения метода POST в соответствующих таблицах БД создаются данные о новой задаче.

Полный контракт метода с примерами запросов и ответов передается на согласование разработчикам Backend, архитекторам, аналитикам команд веб- и мобильных приложений. Это описание дополняют требованиями к заголовкам, авторизации и аутентификации запросов.

Контракт может быть передан в документе Word или Confluence, но самый идеальный вариант, когда Вы можете передать его в виде интерактивной Postman- или Swagger-документации.

Возможно, вы уже почувствовали, насколько много деталей важно помнить при проектировании REST API. И это действительно так: за кажущейся простотой скрывается множество деталей и нюансов.

Не удивительно, что проектирование REST API стало частью технического собеседования для системного аналитика, т.к. это часть того, что происходит “под капотом” системы 🧐

🤖 ChatGPT для системных аналитиков: как искусственный интеллект может помочь в проектировании REST API 🤖

В декабре 2022 года родился помощник для профессионалов разных областей — ChatGPT. Созданный на основе знаний всего интернета, этот искусственный интеллект становится помощником и для системных аналитиков, в том числе в проектировании REST API.

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


Пример команды:

Работай как системный аналитик.
Проект - [Название проекта].
[Описание ключевых данных о проекте, важных для решения задачи].
Спроектируй метод REST API: [Название метода].
1. Сделай описание метода - что это и для чего.
2. Опиши логику его работы - алгоритм.
3. Определи формат запросов и ответов, влияние на БД.
Особенности и ограничения: [уточнение требований и особенностей системы].


Следует помнить, что, несмотря на его обширные знания, ChatGPT не является всезнающим. Он может допускать ошибки, и важно уметь отличать корректную информацию от некорректной, которую он выдает в результате выполнения запросов.

Кроме того, ChatGPT не знает уникальной информации о вашей компании или конкретных проектах. Так что, пока он помогает с общими задачами, все тонкости проектирования API вам придется учитывать самостоятельно.

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

Вы с уверенностью говорите о том, как создавали рабочие методы REST API, проверяли их в Postman, а также взаимодействовали с разработчиками в процессе их проектирования. Преимущество перед коллегами, востребованность на рынке и глубокое понимание современных технологий — звучит привлекательно?

Давайте сделаем это вместе!

---------------------------

Практический вебинар:

📚 Как проектировать REST API в Postman: с нуля до работающих методов
📅 25 октября, 19:00 МСК
🔗 ЗАРЕГИСТРИРОВАТЬСЯ

---------------------------

Что вас ожидает:
🔍 Знакомство с проектированием REST API и применением навыка в реальной жизни.
🛠 Практическая работа в Postman: от создания запросов до реализации рабочих методов на заглушках.
🔄 Про связь API с базами данных и другими системами.
🤖 Лайфхаки по созданию дизайна REST API.

Что я жду от вас:
✅ Готовность учиться на практике и активное участие в чате.
✅ Подготовка: ознакомление с базовыми понятиями API до вебинара в нашем Telegrm-канале.
✅ Мотивация и желание стать лучше в своей профессии.

Хотите получить новые навыки? Регистрируйтесь и приходите в онлайн 25 октября!

С нетерпением жду вас на вебинаре! ❤️️