📝 Как создать JSON для REST API метода: упрощенный алгоритм 📝

Одна из самых простых и одновременно сложных задач - описать JSON объект для REST API метода. Это действительно просто, если думать в контексте одной задачи.

План:

1. Посмотреть на макет UI (дизайн) или на требования системы, которая будет вызывать наш метод.
Результат: список параметров на русском или другом языке.

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

3. Собрать в структуру JSON. Из сложного на этом этапе только понять, что лучше сделать вложенным объектом, что в массив, а что оставить в “плоском списке”.
🔗 Руководство по JSON тут
🔗 Онлайн-валидатор (проверка соответствия формату)
Результат: JSON-объект(-ы) для метода.


По факту алгоритм сложнее.
Инструкция выше рабочая, но больше подойдёт для начинающих системных аналитиков, которые только-только знакомятся с REST+JSON. Она направлена на проектирование JSON для одного конкретного REST API метода и не учитывает работу с контекстом всего проекта.

Кстати, у программистов в работе с полным контекстом проекта та же проблема. Они получают задачу с требованиями на реализацию REST API метода, проверяют, был ли такой объект данных уже когда-либо создан по коду, и если нет, то программируют ровно по вашим требованиям, не думая о будущем.

Так создается проблема “разношерстных” и сложных API в будущем.

Это как начинать заливать фундамент для строительства дома без понимания, что на нем будет стоять - 1, 2 или 3-х этажный дом, кто и для чего им будет пользоваться. Может повезет, а может придется всё переделывать.

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

Поэтому для опытных аналитиков в работе над созданием REST API метода всегда больше шагов 👀

Полный гайд покажу в следующем посте 👇

#RestApiGa

👇👇👇

➕➕ 4. Описываем постановки задач на конкретные REST API методы POST, GET, PATCH и другие.
Используем для них созданный полный JSON-объект. Урезаем / дополняем его по ситуации, в зависимости от потребностей клиентов (Frontend/UI или внешних систем, которые хотят получать от нас данные).

Результат: Дополняем постановки задач на отдельные REST API методы.

Так мы проектируем дизайн JSON до постановок задач на отдельные REST API методы - начинаем с анализа полного контекста требований, создаем общий JSON-объект для переиспользования в постановках задач, и наконец ставим задачи.

Все описанные этапы важны, чтобы получился аккуратный, логичный и удобный REST API для его будущих пользователей 🤝

#RestApiGa

📝 Как создать JSON для REST API метода: полный алгоритм 📝

Этот алгоритм направлен на разработку полного JSON-объекта и переиспользование его во всех методах REST API. То есть аналитика будет не для одного метода REST API, а для всех POST, GET, PATCH и других методов к разработке для управления данными об объекте.

Полный дизайн JSON - это, как правило, дизайн для метода получения информации об объекте, JSON-ответ для метода GET /object/{objectId} (пример: GET /trainers/{trainerId}).


➕➕0. Так как в REST API мы создаем, изменяем, читаем и удаляем объекты данных, то сначала нужно письменно или мысленно выделить список всех методов, где будет использован объект.

Результат: список методов POST, GET, PATCH и других для управления данных об одном объекте, для всех ролей пользователей. Создается с использованием CRUD-модели.

➕ 1. Посмотреть на макеты UI (дизайн) или на требования системы, которая будет вызывать наши методы по каждому методу, чтобы составить список входных и выходных параметров.

Результат: Список параметров на русском или другом языке под каждый отдельный метод POST, GET, PATCH и другие.

➕➕ 1.1. Собрать общий список параметров по всем методам: дубли убрать, но и помнить, что будут параметры, которые есть в одном методе, но не нужны для другого.

Результат: Список параметров полного JSON-объекта на родном языке, которые можно записывать и получать через все REST API методы для одного объекта.

➕ 2. Проверить по БД, что ничего не потеряли и все нужные данные использованы.

Результат: Список параметров полного JSON-объекта обновлен.

➕➕ 3. Собрать в структуру JSON. Из сложного на этом этапе только понять, что лучше сделать вложенным объектом, что в массив, а что оставить в “плоском списке”.
🔗

Руководство по JSON тут

🔗

Как понимание БД помогает при создании JSON

🔗

Онлайн-валидатор JSON

Результат: Полный JSON-объект для метода.

☝️☝️☝️продолжение неожиданно сверху 😀

#RestApiGa

🌱 Открытый онлайн-вебинар по REST API через 2 дня 🌱

Коллеги, напоминаю про предстоящий вебинар в эту среду:

📚 Разбор задач по REST API: что нужно аналитику для работы и собеседований
📅 24 июля, 19:00 МСК
📅 Добавить в календарь

План:
1. Обзор теории и примеров по REST API
2. Практика по теоретическим вопросам
3. Разбор задач с собеседований
4. Как создать портфолио с использованием Postman

🟢 ПОДРОБНОСТИ И РЕГИСТРАЦИЯ

📝 Применение инструкции по созданию JSON в приложении #GetGym 💪

Привет! Вчера опубликовала для вас инструкцию по разработке полного объекта JSON для REST API метода. Закрепление её на примере считаю обязательным пунктом моих публикаций.

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

Для их реализации в работу беру задачу:

Описать полный JSON-объект тренера.

Она нужна перед проектированием конкретных REST API методов.


Почему лучше начинать с этого шага?

💝 После его выполнения вы сможете копировать полный объект и переиспользовать его для всех методов, убирая и добавляя параметры по мере необходимости 💝

Это удобно и аналогично делают программисты по коду!

При описании документации метода REST API в инструменте Swagger также используется подобный подход. Серьезные отличия бывают только для JSON в метод POST - в нем на вход в основном куча id-шников. Для всего остального показанная схема работает.

📌 Инструкция с разбором примера во вложении к посту 🔥 Скачиваем и сохраняем в библиотеку материалов от GetAnalyst.

#RestApiGA

Работа системным аналитиком всегда была для меня источником радости. Профессия дала много возможностей для роста в части софт- и хард-скилов.

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

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

Вся моя карьера помогает формировать широкий кругозор и получать много ценной информации.

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

Я легко берусь за любые задачи благодаря большому опыту в разных предметных областях. Я убеждена, что системные аналитики, которые готовы учиться и расти, могут достичь большого успеха в жизни. И не только в системном анализе 🙂

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

Привет! 👋 Сегодня практика по REST API для системных и бизнес-аналитиков:

📚 Разбор задач по REST API: что нужно аналитику для работы и собеседований
🕖 19:00 - 22:00 МСК
🟢 РЕГИСТРАЦИЯ

Разберем теорию по REST API, поработаем с вопросами технических собеседований на системного аналитика, включая решение практических задач.

Объясню, как разрабатывают вопросы и задания по REST API для собеседований в компаниях, принцип проверки, и как это связано с реальной работой. Эта часть будет полезна для руководителей.

Разберетесь с двумя инструментами, которые каждый день помогают мне в работе, и узнаете лайфхаки по созданию портфолио в Postman.

🗒 Правила и напоминания
✔️ Работать с компьютера.
✔️ Предупредить родных, котиков и собачек, чтобы не отвлекали - это реальное обучение.
✔️ Пробовать решать задания. Даже если не уверены, что верно. Ошибайтесь или убеждайтесь в своих знаниях! Пробуйте! Это ваша возможность получить опыт.
Если переживаете, при входе на вебинар укажите только имя + первую букву фамилии, или псевдоним.
✔️ Задавать вопросы и сразу получать обратную связь.
✔️ Доступ к записи после встречи будет только у зарегистрировавшихся, так как зрители по всему миру и мы с пониманием относимся к тому, что у кого-то ночь. Информация будет на почте.

До вечера, коллеги! 🙂

❗️Уже через 3 часа❗️

Практический вебинар с Екатериной Ананьевой!

📹 Разбор задач по REST API: что нужно аналитику для работы и собеседований
⏰ 19:00 МСК

Ссылку на прямой эфир пришлем в канал за 15 минут до начала.

Не могу остановиться, пересматриваю на повторе 😁

Руководители, не пугайте младших коллег, особенно джунов 💜 Им и так страшно каждый день, их нужно поддерживать и подбадривать.

Коллеги джуниоры, не пугайтесь нас и происходящего в IT. И вы все эти фокусы выучите 💛

Минутка добра и юмора перед пятницей. Всем хорошего настроения!

🟡 Пример постановки задачи на Backend / REST API 🟡

Мне нравится, когда материал доведен до идеала. Поэтому после нашей онлайн-практики доработала шаблон постановки задачи на REST API метод, с которым мы работали.

Метод:
Получение списка тренеров проекта #GetGym

Особенности и подвохи:
- Корректно описать элементы для фильтров.
- Учесть, что могут быть нужны элементы пагинации (постраничное переключение).
- Описать поведение при расширении списков.

Результат:
🔵📘 Заполненный шаблон для Confluence (прямая ссылка на загрузку)
🟠📙 Пример постановки задачи в Postman (прямая ссылка на онлайн-документацию)

Сохраняем в избранное и делимся с коллегами 🧡💙

#RestApiGA

🌱 Разбор задач по REST API: доступ к вебинару 🌱

✔️ Регистрация закрывается сегодня: 26 июля, 19 Мск
✔️ Если уже были зарегистрированы на основной эфир, повторно регистрироваться не нужно
✔️ Письмо с доступом придёт на ваш email в вск утром (проверьте, чтобы не попало в папки СПАМ или Промоакции)
✔️ Доступ будет только в вск и пн
✔️ В канале анонсов и ссылок не будет

📚 Разбор задач по REST API: что нужно аналитику для работы и собеседований
📅 28,29 ИЮЛЯ (ВСК,ПН)
🔗 ПОДРОБНОСТИ И РЕГИСТРАЦИЯ

Желаем вам отличных и продуктивных выходных! ☀️

3 страха, которые губят специалистов

😒 Неуверенность в себе и своих знаниях.
😒 Боязнь не справиться с задачей и сделать ошибку.
😒 Беспокойство, что не будет возможности применить новые знания.

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

▪️ Чтобы преодолеть тревогу и продолжить развиваться, важно использовать свои страхи, как точки роста.
Участвуйте в проектах, которые вызывают неуверенность, чтобы развить уверенность и выйти за пределы зоны комфорта.

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

▪️ Постоянно изучайте новые технологии и инструменты анализа данных.
Например, сейчас актуально осваивать AI (ChatGPT).

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

▪️ Ищите возможности для профессионального развития: книги, конференции, курсы обучения, семинары, вебинары, работа с наставником.

▪️ Практикуйтесь.
Сколько бы знаний ни получили в теории, без практики они приравниваются к нулю. Всегда ищите возможность сразу опробовать новое!

Попробуйте относиться к себе, как к самому крутому и важному проекту в жизни ❤
Пропишите стратегию и план развития. Отмечайте прогресс.

Поверьте, когда посмотрите на себя со стороны, увидите сколько уже вложено, то уверенности в себе станет гораздо больше 💎

Когда впервые сталкиваешься с задачей проектирования REST API, особенно имея опыт работы с проектированием интеграций, то кажется, что это просто.

Но на деле можно столкнуться со следующими проблемами:

✖️ В одном месте эндпоинты /user, а в другом /documents. А как правильно?
✖️ В одном месте метод называется POST /createDocument, а в другом POST /user
✖️ А почему у нас в API все методы POST
✖️ Для метода на изменение данных выбрать PUT или PATCH?
✖️ А мы тут удалить документ из списка хотим. На экране его скроем, а в базе оставим. Что брать? PUT, PATCH или DELETE для API?
✖️ А в JSON мы делаем "userId" или "user_id" или "user-id"?
✖️ А если у нас пустой список, то возвращаем [] или HTTP-404? И вообще в каком формате у нас ошибки?

И это лишь малая часть вопросов при разработке дизайна REST API. Нюансов много. И вариантов решений всегда несколько.

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

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

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

Создание гайда по дизайну REST API помогает стандартизировать процесс проектирования. Каждый разработчик может использовать гайд как руководство, что сокращает время на обсуждение вопросов и принятие решений. Гайд также помогает новым членам команды быстрее освоиться и начать работать с проектированием API.

Я считаю, что гайд по дизайну API - неотъемлемая часть процесса разработки. И я помогаю командам и компаниям его прорабатывать, а также делюсь этими знаниями со своими учениками.

🆘 Привет! Нужна помощь с REST API 🆘

Давайте сделаем требования еще к паре методов для проекта #GetGym.

👉 О проекте GetGym для сети фитнес-клубов
👉 Figma
👉 БД

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

Вопросы сейчас появятся
👇👇👇

💻 Какой метод и URL следует использовать для записи на тренировку у конкретного тренера в приложении #GetGym? 💻

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

Что сразу взяла на вооружение:

1️⃣ По дизайну Figma, мы наблюдаем последовательность:
Список тренеров -> Информация о тренере -> Расписание -> Запись на выбранный слот

2️⃣ POST и PUT можно использовать для создания данных.
Запись на тренировку - скорее создание нового appointment (встречи) / workout (тренировки). Также, как следствие записи, возможно изменение кол-ва свободных мест на занятие в расписании.

Разбираю ответы.

🧐 1) POST /trainer/{trainerId}/schedule/{scheduleId}/workout
Ок, т.к. POST. Отличная логическая цепочка, соответствующая UI.
Но оооочень длинная! Уровень 5 (кол-во /) в URL вызывает тревогу 🥲

❗️Можно укоротить до:
✔️ POST /schedule/{scheduleId}/workout
✅ POST /workout (тогда в тело body надо будет обязательно передать scheduleId, чтобы было понятно к какому тренеру и на какое время записываемся)


👎 2) PUT /trainer/{trainerId}/workout/{workoutId}
Ну вроде ок, т.к. PUT. Но все же POST для создания больше предназначен.
Упустили на какое время в расписании мы записываемся - scheduleId.
Даже если добавим в тело, то зачем тогда в начале /trainer/{trainerId}/?
Это будет понятно из scheduleId по БД. Не берем этот вариант.


👎 3) POST /schedule/{scheduleId}/trainer/{trainerId}/workout
Ок, т.к. POST. А вот иерархия кривая. мы сначала смотрим тренеров, а потом их расписание, но не наоборот.


👎 4) PATCH /trainer/{trainerId}/schedule/{scheduleId}/workout
Вообще не ок - PATCH. Изменять пока нечего.


Итого:
👌 POST /trainer/{trainerId}/schedule/{scheduleId}/workout - ОК
🤝 POST /workout с scheduleId в body - идеально

О вопросах вкусовщины. В вариантах упустила окончания s. Когда делала постановку задачи на список тренеров, использовала его. Кто заметил - молодцы! 😁

#RestApiGA