💾 Гайд по созданию JSON + полезные ссылки 💾

JSON - это текстовый формат сообщений для обмена данными в Интернете, в частности через программный интерфейс REST API.

Данные JSON это пары ключ-значение.

Пример:

{
"id": "1df398dd-32bf-474d-a1a5-222851847801",
"name": "Петр",
"email": “petr@mail.ru”
}

Слева в "" всегда ключ, а справа, после : всегда значение.


JSON поддерживает всего несколько типов данных:

✔️ Number (Целые и дробные числа): 12, -3455 или 24.5
✔️ String (Строки): “Строка всегда в кавычках” или “” (пустая строка)
✔️ Boolean (да-нет. флажок, логический тип данных): true или false
✔️ Array (Массив или список): [“элемент 1”, “элемент 2”, “элемент 3”]
✔️ Object (Объект данных, вложенные JSON): { "name": "Иван" }
✔️ null (Пустое значение): null

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


Простота и легкость чтения человеком сделали JSON основным выбором для многих приложений.


JSON используется в REST API, GraphQL, файлах-конфигураций для систем.


Подробнее, деталях, с примерами и дополнительными ссылками, рассказала всё в мини-книге по JSON. Прикреплена к посту.

#RestApiGA

📋 REST API метод для получения списков - POST или GET? 📋

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

Давайте на примере проекта #GetGym разберём вопросы с неоднозначными ответами:

Просмотр списка тренеров через мобильное приложение клиента.

Список можно фильтровать по специализации (например, кардио, силовые тренировки, йога), опыту, рейтингу и доступности.

❓Какой метод на получение списка выбрать? GET или POST?
Очевидно, что GET! Но… 🙂


Но для работы с некоторыми списками бывают исключения. Когда у запроса на список данных большое количество фильтров, лучшим решением может стать POST. Почему так?

Метод GET не поддерживает тело для запроса body, то есть JSON в него передать нельзя. Получается, что все фильтры потребуется отправлять через query-параметры запроса.

Пример для списка тренеров:

GET https://getgym.com/api-users/v1.0/trainers?name=Вячеслав&location=Central GetGym&....

query-параметры после символа ?


Если для списка тренеров фильтров всего 4 согласно заданию и GET отлично подходит, то что будет, если у вас маркетплейс, в котором на товар может быть 50 фильтров?

Все 50 разных видов фильтров пойдут в URL? 🤔

Продолжение 👇

📋 REST API метод для получения списков - POST или GET? 📋

Продолжение 👇

Когда необходимо реализовать большое количество фильтров для получения списка, то решение отправлять их все в URL запроса как query-параметры не лучшее, т.к. это делает URL очень длинным. Это может вызвать проблемы с ограничениями на длину URL в некоторых веб-серверах или браузерах.

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


🤯 Вместо этого, можно использовать метод POST для передачи всех этих параметров в теле запроса в формате JSON:

POST https://getgym.com/api-users/v1.0/trainers

  “name”: “Вячеслав”,
  “location”: “Central GetGym”,
  …
}

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

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

Но читаемость и удобство использования будет лучше у метода POST.

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

И

того:

1. Если для списка используется до 15-20 фильтров и длина строки выглядит адекватной, то берём для списка метод GET и отправляем фильтры в query-параметры.
2. Если для списка используется 15 и более фильтров, то стоит задуматься об использовании POST и переносе всех фильтров в body (JSON) запроса и не следовать рекомендациям RESTful API.

Для метода получения списка тренеров в #GetGym лучший выбор GET. Но помним, что есть альтернативное решение для этой задачи ☝️

А какие методы у вас используются для получения списков данных на проекте? GET или POST?

#RestApiGa

▶ Элементы пагинации (limit, offset, count) в REST API для работы со списками ▶

Когда мы работаем со списками в REST API, почти всегда рекомендуется использовать элементы пагинации (pagination). Особенно, при запросе данных из таблиц БД с большим количеством строк.

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

Ключевые параметры пагинации (допустимы другие названия):

◽️ limit — максимальное количество записей, которые хотим получить в ответе. Query-параметр.
◽️ offset — смещение, с которого начинается выборка данных. Query-параметр.
◽️ count — общее количество записей по запросу. Возвращается в ответе, в body (JSON), вместе со списком.


Пример получения списка тренеров в #GetGym

GET https://getgym.com/api-users/v1.0/trainers

Этот запрос вернет список всех тренеров. Но что, если тренеров много и нам нужно получать их частями? Вот здесь и пригодятся limit и offset.

Допустим, нам нужно получить по 10 тренеров за раз.

🔸 Первый запрос: получить первые 10 тренеров

GET https://getgym.com/api-users/v1.0/trainers?limit=10&offset=0

🔸 Второй запрос: еще 10 тренеров

GET https://getgym.com/api-users/v1.0/trainers?limit=10&offset=10

🔸Третий запрос: еще 10 тренеров

GET https://getgym.com/api-users/v1.0/trainers?limit=10&offset=20

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



Зачем это нужно? 😎
1. Удобство отображения: Не все данные нужно отображать сразу, особенно если их очень много.
2. Оптимизация: Запросы с меньшим количеством данных обрабатываются быстрее и требуют меньше ресурсов.


Теперь вы знаете, как легко использовать эти параметры для работы с REST API 🙂 Обязательно добавляем их в дизайн метода для приложения GetGym.

#RestApiGA

Проектирование REST API - одна из важных задач, которая лежит на плечах команды разработки Backend 💪

REST API - это программный интерфейс, способ обмена данными между различными системами, приложениями или устройствами. При правильном подходе к проектированию, согласно стандартам отрасли, можно создать удобный интерфейс, который будет максимально эффективен, масштабируем, безопасен и главное - понятен всем участникам разработки (фронтендерам, внешним системам, которые будут с нами интегрироваться).


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

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


Системный аналитик может внести следующий вклад в реализацию задачи по проектированию REST API:

🟢 предоставить информацию о том, какие данные нужны для интеграции систем, и как эти данные должны быть структурированы и переданы в API;
🟢 предложить использовать соответствующие действиям в системе HTTP-методы, такие как GET, POST, PUT и DELETE;
🟢 предложить использовать определенные структуры JSON-объектов для передачи данных в API;
🟢 помочь обеспечить безопасность API, выбрав механизм аутентификации и авторизации;
🟢 документировать API для облегчения взаимодействия между системными аналитиками, тим-лидами и разработчиками;
🟢 тестировать API через Postman, для проверки правильности его работы и соответствия постановке задачи.


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

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

👩‍💻🧑‍💻 Что делает Системный Аналитик: задачи и артефакты 🧑‍💻👩‍💻

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

▫️Какие обязанности у системного аналитика?
▫️Какие результаты он дает IT-команде и на что влияет?
▫️С какими документами работает?

Давайте разбираться вместе с опытными аналитиками!

В эпизоде мы рассказываем о профессии системного аналитика и документах, которые он создает в ходе своей работы (артефактах). 

1:30 - Знакомство с гостями подкаста и их опытом в системном анализе.
6:27 - Текущие обязанности спикеров - главных системных аналитиков.
14:38 - Что создают системные аналитики в процессе работы, что передают разработчикам и другим участникам команды.
23:04 - Структура корпоративного шаблона постановки задачи от системного аналитика - техническая детализация требований.
25:43 - Инструменты системного аналитика для создания диаграмм, подключения к базам данных, тестирования API и другие, которые постоянно используются в работе.
34:00 - Какие требования документировать, а какие нет. Чек-лист аналитики. ФТ (функциональные требования), БТ (бизнес-требования), НФТ (нефункциональные требования), интеграции, базы данных  и другие.
42:28 - Как системный аналитик участвует в проектировании архитектуры? Обязательно ли знать C4 или другие нотации.
47:25 - Другие документы, руководства, инструкции и управленческие документы, которые может создавать системный аналитик. Информационная безопасность.
54:50 - Пожелания и рекомендации от Никиты и Оли по работе с новыми задачами.


Эпизод доступен в:
⏯ Apple Podcast
⏯ Яндекс.Музыка
⏯ YouTube
⏯ Telegram
⏯ Castbox
⏯ Spotify


Ведущая:
🌟 Екатерина Ананьева 

Гости:
🌟 Никита Финько, Главный аналитик в Росбанк
🌟 Ольга Пашкова, Руководитель отдела системного анализа в СберЗдоровье

Подписывайтесь, ставьте реакции и делитесь с коллегами! 🔥

🎤 Ничего не получится. Особенно, если не пробовать 🎤

Начинается третий месяц моих занятий по публичным выступлениям на английском.

🧐 Что я думаю:
1. Напрягает акцент.

2. Уровень грамотности 50-50. Меня понимают, но мне не нравится этот факт.

3. Мне кажется, что не смогу донести суть и смысл того, что говорю.


☺️ Что мне говорят:
1. Акцент прекрасен! Оставь его!

2. Всё понятно! Это вообще круто, что ты занялась публичными выступлениями на неродном языке. У тебя отлично получается и будет еще лучше.

3. Обратная связь от группы после выступлений:

“Я опять узнал новое про бизнес разработки, мне каждый раз интересно слушать про твою работу!”

“Наконец-то я понял что имеют ввиду наши IT-шники, когда говорят про API”

“Твой способ подачи вызывает удовольствие, ты как будто поешь”

В группе никто с ИТ особо не знаком, только один бывший программист 💻

Факты:

🎬 В первый месяц я говорила очень напряженно и монотонно, фокусировалась на грамматике и акценте.

В итоге на записях был слышен ооочень сильный акцент. Грамматика была ок и было мало “эээ”, “мммм”, “аааа”. Хотя они были.

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



🎬 На этой неделе на выступление я переключилась сразу с вебинара по Интеграциям. Времени на подготовку не было. Фокус сейчас на другом.

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

Сливаться в последний момент я не умею. Так что выступила без подготовки, забив на волнение: опыт в ИТ и несколько выступлений на английском до этого должны были помочь.

- Я сделала “ээ”, “аа”, “мм” 29 раз за 11 минут 😀
- Акцента было меньше. Грамматика не поменялась.
- Структура моих докладов и презентации восхищают.
- У меня мелодичный голос, когда я расслабленно вещаю.


Итог:
Пока я между состояниями “серьезное лицо и монотон” и “эээ, я могу переключать ноты в голосе, мм, и, эээ, наверное улыбаться”. Зато пробую.

В любом случае, прогресс есть, что радует 🥳

👇

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

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

Да, часто нет времени, некогда. Слишком много других задач и не до этого. Желание отложить на потом, и сначала подготовиться получше, как-будто это что-то поменяет.

🌱Лучше пробовать, ошибаться и делать неидеально, чем стоять на месте.

Таков мой выбор. И результаты работы над собой в прошлом напоминают об этом каждый день.

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

📝 Как создать 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