SashaBus
Местный
- Тема Автор
- #1
REST (Representational State Transfer) — это архитектурный стиль для API. Если ты делаешь бэкенд, ты почти наверняка будешь делать REST API. Давай разберём правила хорошего тона.
Ресурсы и методы.
Ресурс — это сущность, с которой работаем (пользователи, статьи, товары). Методы HTTP говорят, что именно делать:
API будет меняться. Чтобы не сломать старых клиентов, добавляй версию в URL: /v1/users, /v2/users. Можно в заголовок, но проще в URL.
Документация.
Без документации твой API — чёрный ящик. Используй Swagger/OpenAPI: описываешь эндпоинты в YAML или прямо в коде (аннотации), а Swagger генерирует красивую документацию и даже тестовый клиент.
Вайб: Когда фронтендер пишет тебе «твой API — конфетка, всё понятно из документации» — это высшая похвала. Если он пишет «чё за херня, почему не работает?» — возвращайся к этой статье.
Ресурсы и методы.
Ресурс — это сущность, с которой работаем (пользователи, статьи, товары). Методы HTTP говорят, что именно делать:
- GET /users — получить список пользователей.
- GET /users/5 — получить пользователя с id=5.
- POST /users — создать нового пользователя (данные в теле запроса).
- PUT /users/5 — полностью обновить пользователя 5.
- PATCH /users/5 — частично обновить пользователя 5.
- DELETE /users/5 — удалить пользователя 5.
- Используй существительные во множественном числе: /products, /orders, /articles. Не /getProduct.
- Не вкладывай слишком глубоко: /users/5/orders — нормально, /users/5/orders/7/items/12 — уже сложно.
- Для фильтрации используй query-параметры: /products?category=electronics&price_min=100.
- 200 OK — всё хорошо.
- 201 Created — ресурс создан (после POST).
- 204 No Content — успешно, но тело ответа пустое (часто для DELETE).
- 400 Bad Request — ты прислал неверные данные (например, email без @).
- 401 Unauthorized — не авторизован (нет токена).
- 403 Forbidden — авторизован, но нет прав (например, обычный пользователь пытается удалить админа).
- 404 Not Found — ресурс не существует.
- 422 Unprocessable Entity — данные валидны по формату, но логика не позволяет (например, пытаешься купить товар, которого нет в наличии).
- 500 Internal Server Error — ошибка на сервере (не твоя вина как клиента, но твоя как разработчика бэка).
API будет меняться. Чтобы не сломать старых клиентов, добавляй версию в URL: /v1/users, /v2/users. Можно в заголовок, но проще в URL.
Документация.
Без документации твой API — чёрный ящик. Используй Swagger/OpenAPI: описываешь эндпоинты в YAML или прямо в коде (аннотации), а Swagger генерирует красивую документацию и даже тестовый клиент.
Вайб: Когда фронтендер пишет тебе «твой API — конфетка, всё понятно из документации» — это высшая похвала. Если он пишет «чё за херня, почему не работает?» — возвращайся к этой статье.