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

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

Привет! Продолжим разбор квиза по REST API 🙂

6. Какой метод и эндпоинт используются для получения списка всех зарегистрированных устройств в системе умного дома?

❌ GET /devices/all
Дополнения /all и /list для получения списков избыточны, так как достаточно того, что в эндпоинте у нас нет указателя на конкретный объект.
GET /devices - мы получаем список.
GET /devices/{deviceId} - мы получаем умное устройство по его id.


❌ POST /devices/list
За получение данных отвечает метод GET, поэтому POST и PUT нам нам не подходят. Можно было бы POST при большом количестве фильтров, но здесь это не нужно.

✅ GET /devices
Идеальный вариант без избыточных /list и /all.


❌ PUT /devices/list
Аналогично методу POST.


7. Какой метод и эндпоинт подходят для массового удаления умных устройств из системы?


✅ DELETE /devices
Отличное решение, за которое было отдано большинство голосов. Надеюсь вы догадываетесь куда отправить список id к удалению 🙂
query-параметры


И последний легкий вопрос:
9. Какой метод и эндпоинт лучше всего подходят для изменения данных об умном устройстве?

✅ PATCH /device/{deviceId}
Идеальный вариант. К изменению в body передаются только те параметры, которые надо поменять.

❌ POST /device/{deviceId}/update
Можно для изменения данных использовать метод POST, и добавить в конец edit или update, чтобы показать, что мы хотим редактировать. Но зачем, если для этого есть специальные методы PATCH и PUT.
Это возможный вариант REST API или HTTP API, но это не RESTful API точно.

❌ GET /device/{deviceId}/edit
Метод GET рекомендуется использовать только для получения данных.

✅ PUT /device/{deviceId}
Можно, но мне PUT не нравится, т.к. надо передавать все-все данные на вход, даже те, которые обновлять не надо. Считаю избыточным и я бы его не выбрала.



Теория к этому разбору:
Структура URL:
⭐️https://t.me/getanalysts/1602
Про выбор методов:
⭐️https://t.me/getanalysts/1608
⭐️https://t.me/getanalysts/1581

#RestApiGa