📌 Проект по REST API - Электронная Библиотека #ElibraGA 📌

Каждый месяц в канале GetAnalyst мы изучаем навыки для системных аналитиков через разбор проектов.

Этот месяц мы посвятим проектированию методов REST API для приложения электронной библиотеки #ElibraGA.


В ходе разбора темы я буду делать фокус на:
✅ разработку корпоративных стандартов REST API в компании, которые помогают работать над проектом,
✅ документирование REST API в Swagger.


📚 О проекте 👇

Пользователи-читатели:
+ Регистрируются на платформе через веб- или мобильное приложение
+ Оплачивают подписку, которая дает возможность скачивать 1, 3, 5 или 15 книг в месяц.
+ Получают доступ к списку книг
+ Могут скачать книгу

Администраторы платформы:
+ Добавляют новые книги
+ Редактируют или удаляют существующие
+ Просматривают полный список пользователей-читателей
+ Блокируют и активируют аккаунты читателей
+ Смотрят информацию о подписках и платежах


👉 Наши задачи по проектированию REST API методов

▫️ Сделать с нуля методы POST, GET, PUT, PATCH, DELETE
▫️ Научиться описывать JSON
▫️ Создать задачи на разработчиков
▫️ Формировать корпоративный стандарт по дизайну REST API для проекта
▫️ Создать документацию в Swagger (OpenAPI)


Подписаны на канал?
Значит вы участвуете в проекте и получаете новый опыт 🤝


Проект объявляю открытым! 🎉


#RestApiGA

✨ HTTP-методы — это действия, которые надо понимать для проектирования REST API ✨

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

Каждый метод выполняет определённое действие и соответствует логике CRUD-модели (Create, Read, Update, Delete).


Основные HTTP-методы, которые нужно знать при проектировании REST API 👇


✨ POST: создание нового ресурса
Добавить новую книгу в библиотеку.
Зарегистрировать пользователя.
Создать платеж за подписку.


✨ GET: получение ресурсов
Посмотреть список книг.
Получить информацию о выбранной книге.
Просмотреть информацию о своём профиле.
Проверить статус подписки.



✨ PUT: обновление ресурса целиком или создание нового
для полной замены данных ресурса - редактирования, либо для создания нового.

Вызываем PUT (изменить/создать) для книги с ISBN 1234567890:
👉 если книга с таким ISBN уже была создана, то обновить данные по ней целиком, даже если какие-то параметры, как название, не редактируются.
👉 если книга с таким ISBN еще не создана, то создать новую.

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



✨ PATCH: частичное обновление ресурса
для обновления только некоторых полей ресурса - частичное редактирование.
Изменить описание книги. При этом действии в БД поменяется только её описание, и не будет полной перезаписи всех полей, даже если они не менялись, как это происходит при использовании PUT.


✨ DELETE — удаление ресурса
Удалить выбранную книгу
Удалить выбранные книги из списка
Удалить платеж, если он не оплачен.
Удалить книгу из “избранного”.



Распространенные ошибки в REST API:
- Игнорирование назначения методов.
- Использовать все POST вместо рекомендуемых методов.
- Неправильное использование PUT и PATCH.


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

#RestApiGA #ElibraGA

✨ Открыта запись на практическую программу REST API ✨

Если вы недавно интересовались актуальными требованиями к Системным аналитикам, то наверняка видели:

+ Знание стандартов REST API / JSON
+ Опыт проектирования и документирования API
+ Понимание принципов работы мобильных приложений
+ Знание OpenAPI / Swagger для создания REST API документации
+ Навык тестирования API Backend (Postman)

Все эти навыки, в разных формулировках, ожидают от Middle и Senior Cистемных аналитиков, которым предстоит работать с Backend- или мобильными командами, в проектах с интеграциями.




Мы осваиваем их на практике в рамках одного большого проекта на программе:

💻 Дизайн REST API
🗓 Старт 4 февраля 2025
⚡️ Поток с новым форматом:
⚡️ +3 дополнительных месяца доступа к материалам и обратной связи (9 мес)
⚡️ +3 дополнительных онлайн-встречи

🔗 Узнать подробности и записаться

В ходе работы учимся проектировать методы REST API с нуля, глядя на требования, архитектуру, БД и дизайн UI/UX системы.

Проект с подвохами и сложностями, на котором “набиваем шишки”, учимся писать с нуля и структурировать API-документацию, осваиваем ключевые инструменты СА 🛠




👉 В результате вы создаете свой проект API-документации в Postman и умеете запустить работающие REST API методы Backend на заглушках, даже без навыков программирования! 🤩
Это самая весомая и “программистская” часть вашего профессионального портфолио.


🗓 До 27 января
Запись на специальных условиях с дополнительным обучением по БД в подарок, знания которой понадобятся в ходе работы на проекте.


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

🔗 Структура URL для REST API методов на практике 🔗

Разбираем тему на примере методов:
👉 POST /books
👉 GET /books
👉 GET /books/{bookId}
Подробности в документе к посту.


✅ Метод HTTP
Не относится к URL, но тесно связан с ним. Описывала правила выбора в этом посте.

✅ Протокол
В начале любого URL указывается протокол HTTP(s), который обеспечивает передачу данных.

✅ Доменное имя
Основной адрес, по которому можно обращаться к серверу.

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

▫️“api” - указатель на каталог API сервера, может быть название вида api. Это необязательный сегмент, может отсутствовать в URL.
▫️имя api - указывает на конкретный интерфейс API, предназначенный для разных пользователей системы.
▫️v1 - версия API, важна для поддержки совместимости с предыдущими версиями.

▫️books - это ресурс, к которому осуществляется доступ. В данном случае “книга”. Может быть в единственном числе (book).
▫️{bookId} - это параметр в пути URL (path-параметр), указывающий на конкретную книгу по её id в БД системы. Фигурные скобки {} обозначают переменную часть URL, значение которой должно быть предоставлено клиентом (например, идентификатор 78679).


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

В примере:
GET …/books?offset=0&limit=10&name=аналитика&yearFrom=2010
👉 ?offset=0&limit=10 указывает на запрос результатов с 0-го, ограниченный 10-ю результатами на страницу. Это два отдельных query-параметра, которые являются элементами пагинации (постраничного получения данных через API).
👉 &name=аналитика - фильтр на название книги.
👉 &yearFrom=2010 - фильтр на год выпуска книги.



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

#RestApiGA #ElibraGA

Кто не успел записаться на Оптимизацию БД и индексы, то еще можно успеть подключиться к нам сегодня в 19:00 Мск.

+ занятие про распределенные БД на неделе посмотреть.


🔗 Подробности и запись тут


До встречи в эфире! 🙂

🙌 Сводка по проектированию эндпоинтов REST API 🙌

🔗 HTTP-методы
🔗 Структура URL
🔗 Ошибки проектирования методов REST API

Проверим, насколько вы хорошо усвоили материал по эндпоинтам REST API.

Попробуйте ответить на вопросы, а затем сравнить с предложенными ответами 👇


1. Какой метод сделать для регистрации нового пользователя?
❌ POST https://elibraga-online.com/api/public/v1/createUser
В URL дублируется действие (глагол create), которое уже указывает HTTP-метод POST.
✅ POST https://elibraga-online.com/api/public/v1/users
+ Метод POST используется для создания новых ресурсов - регистрация = создание пользователя.
+ users является сущностью, к которой относится запрос.

2. Как получить список авторов с фильтрацией по жанру?
❌ GET .../api/public/v1/authorsByGenre/{genre}
Фильтрация по жанру в данном случае не является частью основного ресурса.
✅ GET .../api/public/v1/authors?genre=fiction
+ Query-параметры позволяют удобно передавать фильтры, такие как genre=fiction. Значение жанра может отличаться, также их можно перечислить через запятую. Это делает запрос гибким и легко расширяемым.

3. Как получить список заказов пользователя?
✅ GET .../api/public/v1/orders
То, что это заказы конкретного пользователя, понимает за счет того, что запрос подписан авторизацией.
✅ GET .../api/admin/v1/users/123/orders
Для админского метода выстроена иерархия от пользователя к заказу для просмотра заказов внутри информации о пользователе.
✅ GET .../api/admin/v1/orders?userId=123
В общем списке заказов в админке можно применить фильтр по пользователю.

4. Как сделать метод отмены заказа пользователем?
◽️DELETE .../api/public/v1/orders/{orderId}
Больше подходит, чтобы показать удаление неоплаченного заказа.
✅ PATCH .../api/public/v1/orders/{orderId}/cancel
Глагол действия на смену статуса вынесен в конец URL, что часто встречается для PATCH (еще бывают archive, pay и подобные).

Сколько правильных ответов получилось?
Задавайте вопросы в комментариях 🙂
Делитесь результатами и доп решениями💡

#RestApiGA #ElibraGA

😨 Headers в REST API: что это и зачем? 😨

Headers – заголовки запроса и ответа в протоколе HTTP.

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

Помогают:
✔️ Определять, как обрабатывать запрос.
✔️ Передавать метаинформацию о данных (системную).
✔️ Настраивать взаимодействие между клиентом и сервером.


Проще всего разобраться с Headers, познакомившись с набором стандартных значений, которые можно нагло копировать в требования к вашим методам REST API 🙂


📌 Request Headers - для запросов

◽️ Authorization
Используется для передачи токенов доступа, ключей API или других данных для авторизации. Используется для проверки доступа к API-методам.

Authorization: Bearer <token>

◽️ Content-Type
Сообщает серверу, в каком формате отправлены данные.
Если сервер не знает в каком формате переданы данные, то он не сможет обработать запрос.
Если его нет в API, то сервер обычно ждёт JSON, если в документации не указано иное.

Content-Type: application/json

Content-Type: application/xml

◽️ Cache-Control
Управляет кэшированием данных на клиенте.
Полезно для работы с экономией трафика.

Cache-Control: no-cache

◽️ Ключи идемпотентности - название придумываете сами
Это уникальный идентификатор для запросов, который помогает избежать дублирования. Например, при повторной отправке платежного запроса сервер проверяет ключ и не создаёт дубль.
Подробнее в подкасте

Idempotency-Key: <unique-key>

◽️ Часовые пояса
Когда система работает в разных регионах, важно учитывать часовые пояса и их можно передавать как обязательные заголовки во всех запросах.
Стандартные названия из моего опыта:

Time-Zone: UTC+3

X-Time-Zone: UTC+3

📌 + помним про Response Headers (заголовки ответов)


Полные подборки стандартных Headers:
🔗 Wikipedia
🔗 MDN


Правильно выбранные Headers помогают удобно передавать все системные параметры для обмена данными, которые не важны для бизнес-логики и алгоритмов работы API-методов.

#RestApiGA

🔥 Книга по JSON в REST API 🔥 + история про собеседования

Нанимаем системного аналитика на проект, где нужно работать с web-, mobile и backend.

Есть публичная REST API-документация. Опубликована на официальном сайте. Протестировать бесплатно нельзя, почитать бесплатно можно.

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


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

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

👌 Тип метода GET, POST, PUT, PATCH или DELETE выбирают правильно почти всегда.

👌 URL делают, не всегда так, как ожидаем. Но хотя бы понимаем, где придётся доучить.

🥲 А вот когда дело доходит до JSON, то тут мы можем смело принимать решение о продолжении диалога.


🔴 👉 Типичные ошибки и недочеты в JSON:
- Незнание типов данных
- Дата и время - про стандарты ISO не слышали
- Умение самостоятельно описать только "плоские" объекты данных, без вложенных структур
- JSON запроса и ответа одинаковые, либо один из них теряется в случае методов, отличных от GET
- Неумение работать со списками - массивы
- Нейминг (именование полей) порой заставляет и смеяться, и плакать
- Отсутствие знаний базовых структур для методов
+ Незнание инструментов, что сразу показывает отсутствие опыта

Это самое-самое, что бросается в глаза с первых минут.
Давайте не будем допускать эти ошибки? 🙂


Руководство по JSON, прикрепленный к посту - ваш будущий помощник и ориентир в проектировании API 📘
В нем собрала самое ключевое, чтобы не валить ваши собеседования и качественно выполнять свою работу 🙌

-----
P.S.
И большой намек к этому посту:
🚨 REST API-документацию компании можно изучить до собеседования, если она есть в открытом доступе.
Это полезно, чтобы понять, что будут ожидать на практике, и посмотреть на подходы работы в компании.
-----

Запоминаем, сохраняем, пользуемся 🙏

#RestApiGA