💥 Завершается запись на REST API на специальных условиях 💥

Предстоит менять компанию и выходить за пределы знаний о системах, с которыми работали? Нужно изучить REST API, Swagger, Postman? Этот пост для вас 🙂

Открыта запись на практическую программу:
📚 Дизайн REST API
🗓 Старт 5 ноября
❗️Следующий поток в онлайн планируется на апрель 2025.

🎁 Для всех, кто запишется на программу до 25 октября, действуют самые выгодные условия + дарим в подарок дополнительное обучение по БД+SQL.

В течение 2-х месяцев вас ждет:
◽️ 8 онлайн-встреч с опытными системными аналитиками.
◽️ Работа над ОДНИМ проектом в течение всей программы.
◽️ Детальный разбор проектирования RESTful API с нуля: от БД+UI до готовых RESTful API методов.
◽️ Практика в инструментах для тестирования и документирования REST API - 🟠Postman и 🟢Swagger.
◽️ Встреча для разбора индивидуальных проектов.


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

Самые приятные сообщения в середине прохождения программы:

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

Это результаты вашей работы, которыми я восхищаюсь! ❤️

Приглашаем вас присоединиться к новой команде по работе с REST API!

Есть вопросы или не уверены, что эта программа актуальна для вас?
Пишите @getanalyst или заполняйте анкету предзаписи. Мы свяжемся с вами, поможем оценить текущие навыки и ответим на ваши вопросы! 🙂

🙌 Продолжение: Разбор тестирования по структуре URL с понедельника 🙌


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

❌ GET https://api.rentacar-project.com/v1.0/cars - GET используется только для получения данных.

✅ POST https://api.rentacar-project.com/v1.0/cars - идеально подходит для создания автомобилей.

✅ PUT https://api.rentacar-project.com/v1.0/cars - метод PUT можно исользовать для методов создания и изменения данных, помогает обеспечивать идемпотентность.

❌ DELETE https://api.rentacar-project.com/v1.0/cars - DELETE используется только для операций удаления.



5. Какой URL и метод следует использовать для обновления данных конкретного пользователя с id=567?

✅ PUT https://rentacar-project.com/api/v1.0/public/users/567 - хороший вариант, PUT используется для полной перезаписи данных в БД.

✅ PATCH https://rentacar-project.com/api/v1.0/users/567 - хороший вариант, PAT CH используется для частичной перезаписи данных в БД.

☑️ PATCH https://rentacar-project.com/api/v1.0/users?userld=567 - можно, но все же указатели на объект рекомендуется держать не в query, а в path-параметрах запроса.

❌ POST https://rentacar-project.com/api/v1.0/users/567 - допустимо для HTTP API, но недопустимо для RESTful API принципов.




Если пропустили тестирование и теорию в понедельник, очень рекомендую вернуться к ним.

Важная теория:
📌 Типы методов
📌 Структура URL
📌 Идемпотентность в API (подкаст)


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

#RestApiGA

🔎 Что влияет на дизайн REST API метода 🔎

Дизайн REST API (или “контракт REST API”) — это договоренность между разработчиками клиентов (Frontend или другие сервера) и разработчиками сервера (Backend) о том, как будут работать методы REST API.

Он включает в себя полное описание API-методов:

✔️ структуры запроса:
+ Метод (GET, POST, …)
+ URL ресурса
+ Заголовки (headers)
+ Тело запроса (body) в формате JSON (или другом)

✔️ и структуры ответа:
+ Статус-код HTTP
+ Заголовки ответа (headers).
+ Тело ответа в формате JSON (или другом).

Его создают Системные аналитики совместно с Backend-разработчиками.


Что важно знать о влиянии разных частей системы на дизайн REST API методов:

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

✅ В БД может быть бардак, а в REST API соберите и структурируйте данные нормально, пожалуйста
Часто внутренняя структура базы данных (БД) не точно соответствует тому, как клиентам удобно получать данные. Это нормально. Задача REST API — преобразовать сложные внутренние данные в понятную, логичную и структурированную форму для внешнего пользователя.

✅ Названия параметров в БД и в REST API не должны соответствовать
То, как называются колонки в базе данных, не всегда понятно для пользователей API. Убедись, что параметры и названия в REST API интуитивно понятны и соответствуют бизнес-логике, а не внутренней реализации системы.

✅ Количество методов REST API не зависит от количества экранов
У нас может быть один экран на фронтенде, который зависит сразу от нескольких API методов. Или наоборот — один метод может обслуживать несколько экранов. Дизайн API должен базироваться на логике данных, а не на количестве пользовательских интерфейсов.

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

✅ Интеграционные API-методы: под вызовом нашего API-метода скрывается вызов чужого API и они не должны совпадать на 100%
Когда наш API вызывает внешние системы, не обязательно транслировать их ответы один в один. Можно обрабатывать и обогащать данные, либо урезать. Главное дать для клиента API полезную и удобную для использования информацию.

✅ Иногда POST будут использовать для получения данных, или вообще для всего - и это “ок”
Хотя по стандарту POST используется для создания данных в БД, бывают случаи, когда его используют для получения или выполнения других операций. Это зависит от архитектуры и бизнес-логики.

✅ Стандартизируйте
Старайтесь сделать единый дизайн запросов и ответов для всех методов по CRUD-модели одной сущности, с учетом исключений для отдельных методов.


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

#RestApiGA

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

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

В разработанной мною API-документации Postman для проекта #RentACar описание ошибок - одна из главных частей документации.

Знание и правильное использование кодов 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

Друзья, делитесь, а какие у вас были озарения после стажировки?😎

#GAhahaha

📄 Шаблон постановки задачи на REST API метод 📄

Структура требований для разработчиков Backend, которую можно использовать в Confluence при описании контрактов REST API методов.

1. Название метода
2. Общее описание
3. Алгоритм работы
4. Пример запроса
5. Пример ответа: успех и ошибки
6. Маппинг данных
7. Дополнительные требования

Аналогичную структуру постановки задачи можно реализовать через инструменты документирования и тестирования API - Postman и Swagger.

Подробнее в статье:
🔗Структура постановки задачи на REST API метод

Также по ней очень удобно делать команды к ChatGPT - это Искусственный Интеллект, который как младший системный аналитик помогает в разработке требований и делает половину работы за вас 🙌

#RestApiGA

📚 Что почитать и посмотреть по REST API: подборка материалов от GetAnalyst 📚

У нас много новых участников в сообществе 🙌 И…! Вместо того, чтобы рассказывать о себе, я решила сделать для вас подборку из полезных материалов по проектированию REST API. Так вы лучше узнаете меня - Екатерину Ананьеву - не на словах, а на деле 🙂

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

(В) Связь базы данных и дизайна REST API

(C) Простыми словами про API

(В) Postman: навык тестирования REST API за вечер

(В) Проект “Система для автосервиса” - видео-обучение.
1. Системный анализ проекта с нуля: Сбор бизнес-требований, погружение в контекст
2. Системный анализ для проекта: определение сущностей и проектирование логической модели БД
3. REST API с нуля: дизайн методов для работы менеджера с заявками автосервиса

(C) Postman: Практическое руководство с примером тестирования открытого API

(С) Postman: Практическое руководство с примером тестирования открытого API - 2.0

(П) Вопросы и ответы по REST API: собеседование на СА

(С) Мини-книга с подробным разбором формата сообщений JSON

(В) Собеседование на СА: разбор задачи на асинхронные запросы в REST API

(C) Структура постановки задачи на REST API метод

(П) gRPС vs REST - что выбрать для проекта

(C) Проектирование REST API: спорные вопросы с проектов и собеседований на системного аналитика (и не только)

Также вы можете найти у нас мини-обучения по REST API и практическую программу "Дизайн REST API" для опытных аналитиков.

(В) Видео
(П) Подкасты
(С) Статьи

Делитесь с коллегами, особенно с джунами и мидлами СА!
Сохранили? ❤️

#RestApiGA