🙌 Сводка по проектированию эндпоинтов 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