(Их часто спрашивают на собеседованиях)
1. Понятные имена ресурсов
❌`GET /get-all-orders`
✅`GET /orders`
2. Корректное использование HTTP-методов
-
POST /users — создать пользователя -
GET /users/123 — получить пользователя -
PUT /users/123 — заменить полностью -
DELETE /users/123 — удалить 3. Идемпотентность
Клиент отправляет:
POST /payments
Idempotency-Key: abc-123
Если запрос повторится, сервер должен вернуть тот же результат, не создавая операцию заново.
4. Версионирование API
Рекомендуемый вариант — в URL:
GET /v1/products/42
GET /v2/products/42
5. Правильные статус-коды
Если пользователь не найден:
❌ `200 OK { "error": "user not found" }`
✅ `404 Not Found`6. Пагинация
Пример:
GET /articles?page=2&limit=50
Ответ должен содержать элементы 51–100.
7. Фильтрация и сортировка
Пример:
GET /orders?status=shipped&sort=-created_at
8. Безопасность
Использование JWT в заголовках:
Authorization: Bearer <token>
9. Rate limiting
Например: 100 запросов в минуту.
После превышения — вернуть:
429 Too Many Requests
10. Кэширование
Запрос:
GET /blog/posts/123
Ответ содержит:
ETag: "abc"
Повторный запрос:
If-None-Match: "abc"
Если не изменилось — 304 Not Modified.
11. Документация
Используй:
- Swagger UI
- OpenAPI
Разработчики должны видеть схемы, параметры и иметь возможность тестировать запросы.
12. Быть прагматичным
Иногда лучше так:
POST /auth/login
чем строго REST-подход:
POST /sessions
Хороший API читается как логичная, предсказуемая система и экономит время всем, кто с ним работает.
👉 Java Portal