💫 Структура URL запроса в REST API 💫

1️⃣ Протокол (обяз.): http/https.

2️⃣ Доменное имя (обяз.): адрес API в сети Интернет.

3️⃣ Путь (Path), составная часть URL.

++ Базовое описание API:
+ api - указатель на каталог API, необязательная часть пути, если на этом доменном имени не работает сайт системы.
+ Имя API - папка с группой API, объединенных общей логикой, настоятельно рекомендуется указывать.
+ Версия API - настоятельно рекомендуется указывать.

++ Название endpoint-а, допустима иерархия:
+ Имя ресурса (обяз.) - имя объекта данных, которым необходимо будет управлять (пользователь user, устройство device, и другие). Может быть как в единственном, так и во множественном числе. Зависит от выстроенных договоренностей внутри компании или проекта.
+ Указатель на объект - уникальный идентификатор ресурса в системе, необязательный, если запрашивается список.
+ Продолжение иерархии - имя вложенного ресурса + указатель на него, или глагол изменения состояния, возможны разные варианты в зависимости от требований к системе.

4️⃣ Query-параметры запроса (Query-parameters): параметры, которые идут после ? и разделяются &, обычно используемые в списках для их фильтрации, сортировки и постраничного получения (пагинации). Иногда использую для передачи указателя на объект.


Вариантов построения URL много: правильные и неправильные, рекомендуемые и нерекомендуемые. Только структуре URL и принципам его построения в программе дизайна REST API для системных аналитиков отводится почти 3-х часовая практика, чтобы разобраться в деталях!

Пост важный. Поможет отвечать на вопросы собеседований.

#RestApiGa

💫 РАЗБОР ПРИМЕРА: Структура URL запроса в REST API 💫

Получить информацию о конкретном умном устройстве по его уникальному идентификатору в системе:
GET https://smarthomega.com/api/user-api/v1/devices/{deviceId}


1️⃣ Протокол:
В начале любого URL указывается протокол, используемый для доступа к ресурсам.
В примере это https (HyperText Transfer Protocol Secure), который обеспечивает защищенную передачу данных.


2️⃣ Доменное имя:
smarthomega.com.


3️⃣ Путь (Path):
Путь включает в себя один или несколько сегментов, разделённых слешами (/).

+ api - указывает на то, что будет выполнен переход в каталог API сервера.
+ user-api - указывает на конкретный интерфейс API, предназначенный для обычных пользователей системы. Также это могло быть указание на API для администраторов или умных устройств в системе.
+ v1 - означает версию API, что важно для поддержки совместимости с предыдущими версиями.

+ devices - это ресурс, к которому осуществляется доступ, в данном случае “умные устройства”.
+ {deviceId} - это параметр в пути URL (path-параметр), указывающий на конкретное устройство по его id. Фигурные скобки {} обозначают переменную часть URL, значение которой должно быть предоставлено клиентом (например, идентификатор 1234567 конкретного устройства).


4️⃣ Query-параметры запроса (Query-parameters):
В приведенном примере параметры запроса не указаны, но они могут быть добавлены после знака вопроса ?.

Пример с query-параметрами:
GET https://smarthomega.com/api/user-api/v1/devices/{deviceId}?page=2&limit=10

?page=2&limit=10 указывает на запрос второй страницы результатов с 10 результатами на страницу. Это два отдельных query-параметра, которые являются элементами пагинации (постраничного получения данных через API).


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

#SHGA #RestApiGA

😱 Вопросы квиза по REST API с неоднозначными ответами про URL 🥲

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

1. Какой из перечисленных компонентов является обязательным в структуре URL для REST API?

✅ A) Протокол
Да. Есть всегда. Обязательная часть URL REST API.

❌ B) Параметры запроса
Здесь нет уточнения какие. Могут быть query, могут быть path. Но в любом случае, как мы разобрали в теоретическом посте и в примере, оба вида параметров не обязательны и зависят от конкретного REST API метода.

❌ C) Фрагмент
В составе URL могут присутствовать фрагменты (Fragments). Это необязательный компонент, который следует после символа # и обычно используется для обращения к конкретной части документа. В API URL фрагменты вообще не используются, но можно, если очень хочется.

❌ D) Только Path-параметры запроса
Не обязательные, только при запросе конкретного ресурса.


3. Как правильно указывать название ресурса в endpoint-е REST API?

❌ A) В единственном числе. GET /device/{deviceId}
Так можно.

❌ B) Во множественном числе. GET /devices/{deviceId}
И так тоже можно.

✅ C) Можно и в единственном числе, и во множественном
Это верный ответ.
Действительно, можно и так, и так. Но нужно ориентироваться на то, как названы остальные эндпоинты в проекте.


Изучили теорию, разобрали практический пример и затем детализировали каждый ответ по квизу 🙌

Поддержите пост ❤️, если было полезно или нравится формат. Всегда рада и благодарна за вашу вдохновляющую поддержку ❤️

2️⃣0️⃣0️⃣ HTTP-коды ответов в REST API методах 2️⃣0️⃣0️⃣

HTTP-коды ответов являются неотъемлемой частью структуры ответа REST API. Это стандартизированный способ для сервера сообщить клиенту о результате обработки его запроса.

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

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

❗️HTTP-коды ответов, которые нужно знать❗️
Картинка прикреплена к посту.
+ Коды успеха 200-204е
+ Коды перенаправления 300-е (используются крайне редко, об их существовании просто надо знать)
+ Коды ошибок клиента 400-404е
+ Коды ошибок сервера 500-504е

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

Например, при возврате пустого списка может использоваться 204 (No Content), или 200 с пустым body, если такое поведение ожидаемо, или 404 Not Found, если отсутствие данных является неожиданным.

Много деталей, которые системные аналитики должны проработать при проектировании логики работы и дизайна каждого REST API метода.

Понимание и правильное применение HTTP-кодов в REST API — важный навык для любого системного аналитика 🚀

#RestApiGA

2️⃣0️⃣1️⃣ Вопросы квиза по REST API связанные с HTTP-кодами ответов 2️⃣0️⃣1️⃣

Вопросы в квизе по кодам HTTP были только на знание теории. Хотя вопрос 4 подразумевал не только знание теории, но и умение применить её разными способами на практике. Информации в предыдущем посте достаточно, чтобы на них ответить. Давайте разбираться!

2. Какой код статуса HTTP используется для указания того, что операция прошла успешно, и в результате был создан новый ресурс?
❌ A) Код 200 (OK) используется для обозначения успешного выполнения запроса. Этот код означает, что запрос был успешно обработан и сервер вернул ожидаемый ответ. Однако, в контексте создания нового ресурса, этот код не является идеальным выбором, так как не указывает на то, что был создан новый ресурс.
✅ B) Код 201 (Created) является правильным ответом на данный вопрос. Этот статус указывает, что запрос был успешно выполнен и в результате был создан новый ресурс. Обычно этот код используется в ответ на POST-запросы, когда результатом является создание нового ресурса на сервере.
❌ C) Код 302 (Found) является кодом перенаправления. Этот статус сообщает, что запрошенный ресурс временно находится по другому URI, на который клиент должен перейти. Этот код не связан с созданием ресурсов.
❌D) Код 404 (Not Found) используется для указания на то, что запрошенный ресурс не найден на сервере.


4. Какой статус код следует возвращать, если клиентское приложение запрашивает несуществующую страницу пагинации?

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

4. Какой статус код следует возвращать, если клиентское приложение запрашивает несуществующую страницу пагинации?

✅ A) 200 OK с пустым телом ответа
Код 200 указывает, что запрос был успешно обработан. Это возможное решение в случае, если система допускает возврат пустого списка элементов в ответ на запрос несуществующей страницы пагинации и это общепринятый подход для пагинации в системе.

✅ B) 204 No Content
Код 204 сообщает, что сервер успешно обработал запрос, но не возвращает никакого содержимого: запрос к несуществующей странице пагинации обработан без возврата данных. Можно использовать в случае, если это общепринятый подход к работе с пагинацией в системе.

✅ C) 404 Not Found
Код 404 используется для указания, что запрошенный ресурс не найден. В контексте пагинации, этот код означает, что запрашиваемая страница находится за пределами допустимого диапазона страниц. Он ясно указывает пользователю или клиентскому приложению, что запрашиваемая страница не существует.

✅ D) 416 Requested Range Not Satisfiable
Код 416 обычно используется в контексте HTTP Range Requests, когда клиент запрашивает определённый диапазон байтов из файла, и этот диапазон не может быть обслужен сервером, потому что он не соответствует длине содержимого. Например, если файл имеет размер 500 байтов, и клиент запрашивает байты с 600 по 610.

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


Для этого вопроса я бы предпочла HTTP-200 с пустым телом или HTTP-404. Но! Всё зависит от существующего рядом API, опыта команды и договоренностей в ней.

Изучайте API-документацию внутри и за пределами компании, развивайте насмотренность для проектирования требований к обработке ошибок. Используйте Best Practice в своих проектах! ❤️

#RestApiGA

😎 Как правильно регистрировать: POST /devices или POST /devices/register? 😎

При проектировании эндпоинтов REST API есть важное правило:
НЕ ДУБЛИРУЙ В НАЗВАНИИ ЭНДПОИНТА ДЕЙСТВИЕ-ГЛАГОЛ ИЗ HTTP-МЕТОДА

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

HTTP-методы REST API сами по себе обозначают глаголы по CRUD-модели:
- GET - получить
- POST - создать
- PUT / PATCH - изменить
- DELETE - удалить
Поэтому все действия описываются в них. А в названии эндпоинта - существительное, объект данных, которым управляем.


На примере управления данными об умных устройствах через REST API:

Получить список умных устройств:
✅GET /devices
❌GET /getDevices

Получить информацию об умном устройстве по id:
✅GET /devices/{deviceId}
❌GET /getDevice/{deviceId}

Создать умное устройство:
✅POST /devices
❌POST /createDevice

Изменить умное устройство:
✅PATCH /devices/{deviceId}
❌PATCH /changeDevice/{deviceId}

Удалить умное устройство:
✅DELETE /devices/{deviceId}
❌DELETE /deleteDevice/{deviceId}

Зачем делать “масло-маслянное”, если у нас уже есть глагол-действие в HTTP-методе?
Думайте об этом при именовании эндроинтов.


Иногда всё же возникает необходимость в использовании глаголов в URL, особенно когда дело касается операций, которые трудно описать стандартными методами HTTP. Например:
PATCH /devices/{deviceId}/activate — активация устройства, специфичное действие, которое не укладывается в стандартные CRUD-операции. Но это отдельные ситуации, которых на самом деле ограниченное количество.

Эти случаи допустимы, но они должны быть обоснованными и чётко отличаться от стандартных операций с ресурсами.

Название эндпоинта - существительное, все действия в HTTP-методах. Следуем этому принципу, и ваш API будет более логичным и понятным 🙌

Итого, как правильно: POST /devices (❤️) или POST /devices/register (👍)? 😉

#RestApiGa #SHGA

Какой метод и эндпоинт REST API лучше всего подходит для регистрации нового умного устройства администратором системы? 🧐

Решение:
1. Регистрация устройства = Создание устройства = Метод POST.
2. Устройство = device или любое слово синоним, которое найдём в тесте.
3. Администратором? Будем подписывать запрос авторизацией от имени администратора. Это пойдёт в заголовок Header.

Метод POST /device или аналог нам подойдёт.

По вариантам ответов на вопрос квиза:
❌A) POST /devices/register - нет, тут “масло маслянное”
✅B) POST /device - идеально.
❌C) PUT /admin/device - зачем здесь admin? это эндпоинт, а не полный URL API, про админа все в Header, в информации по авторизации.
❌D) PUT /devices - можно, но лучше POST, он наиболее подходящий.

Доказательства в публичной API-документации:
POST ​/v1​/user - регистрация нового пользователя в сервисе wavesenterprise
POST https://api.multifactor.ru/users - регистрация пользователя в сервисе multifactor

#RestApiGa #SHGA

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

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

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

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

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

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

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

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

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

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

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

🧡 ТОП-5 инструментов для работы с REST API 💚

Привет! Хочу поделиться с вами набором инструментов, которые регулярно использую в работе с REST API. Они постоянно запущены и работают в моем компьютере!

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

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

💚 Swagger (OpenAPI): Представляет собой фреймворк для описания и визуализации RESTful API. Он позволяет вам четко определить структуру вашего API в формате JSON или YAML с использованием стандарта OpenAPI. Это значительно упрощает понимание и использование вашего API как внутри вашей команды, так и для будущих пользователей вашего REST API.

🤍 ChatGPT: Искусственный интеллект, который помогает разработать примеры запросов и ответов REST API, описать маппинги данных, требования к работе логики, документацию. Но его эффективное использование возможно только при знании команд и наличии опыта работы с REST API. Иначе могут быть ошбки и неверные решения.

🖤 JSON Editor Online: Предоставляет удобный способ редактирования и просмотра JSON-сообщений прямо в браузере. Он поможет вам форматировать JSON, выделять синтаксические ошибки.

💙 Confluence: Инструмент для создания и обмена документацией. Вы можете использовать его для документирования вашего API (контракты), описывать архитектуру, логику работы, инструкции по использованию, примеры запросов и ответов, маппинги данных, что поможет вашей команде лучше понимать и использовать ваше API.

Если вы знаете другие важные инструемнты для работы с API, делитесь с коллегами в комментариях 🙌

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

Этот подкаст будет полезен как начинающим, так и опытным аналитикам, которым нужна поддержка и помощь в работе, но кажется, что её невозможно получить. Решения есть. И у вас всё получится 🙌

04:25 - Когда и как обычно приходят новые задачи? Есть ли к этому предпосылки, если это не связано со сменой места работы и ты не уже не джун?
9:52 - Какие ошибки чаще всего допускают, пытаясь решать задачи самостоятельно, без помощи ментора?
20:32 - Как обращаться за помощью в решении незнакомы задач?
32:15 - Пошаговый план в решении незнакомых задач.
38:20 - Оценка влияния задачи на систему - общий чек-лист. Структура системы.
43:09 - В какой момент просить помощи у коллег и можно ли получить негативную реакцию от них?
50:15 - Негативная реакция от коллег при запросе помощи.
56:18 - Как сохранять мотивацию, если начинаешь работу с незнакомой задачей.
1:02:10 - Как влияет отсутствие или наличие ментора на профессиональное развитие аналитиков.

Дополнительные материалы к подкасту доступны по этой ссылке.


Эпизод доступен в:

⏯ Apple Podcast
⏯ Яндекс.Музыка
⏯ YouTube
⏯ Telegram
⏯ Castbox
⏯ Spotify

Подписывайтесь на площадках, мы благодарны за вашу поддержку! 😉