Можно ли использовать GET для получения сущности?

Можно ли использовать GET для получения сущности?

Да, именно для этого и нужен GET. Это один из основных HTTP методов, специально предназначенный для безопасного и идемпотентного получения данных с сервера.

Основные принципы REST

HTTP методы и их назначение

• GET — получение сущности или списка (безопасный, идемпотентный, кешируемый)
• POST — создание новой сущности
• PUT — полное обновление существующей сущности
• PATCH — частичное обновление
• DELETE — удаление сущности

Безопасность означает, что GET не должен менять состояние на сервере. Если ты используешь GET и это изменило данные — это нарушение контракта.

Идемпотентность означает, что несколько одинаковых запросов дают тот же результат. Позвонил в API 1 раз, 10 раз, 100 раз — данные одни и те же. Это позволяет браузерам и кешам безопасно переотправлять запросы при ошибках сети.

Примеры правильного использования GET

GET /api/v1/users/123

Ответ 200 OK:
{
  "id": "123",
  "name": "Иван Петров",
  "email": "ivan@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

GET /api/v1/products?category=electronics&sort=price_asc&limit=20&offset=0

Ответ 200 OK:
{
  "items": [
    { "id": 1, "name": "Ноутбук", "price": 50000 },
    { "id": 2, "name": "Монитор", "price": 15000 }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Варианты получения с параметрами

Query parameters в URL

GET /api/v1/orders?user_id=123&status=completed&limit=10

Используй для:

• Фильтрации (status, category)
• Сортировки (sort=date_desc)
• Пагинации (limit, offset или page, per_page)
• Поиска (query, text)

Path parameters для идентификаторов

GET /api/v1/users/123/orders/456

Получи заказ #456 пользователя #123.

Headers (если нужно передать чувствительную информацию)

GET /api/v1/protected-resource
Authorization: Bearer eyJhbGciOiJIUzI1NiI...

Когда НЕ использовать GET

Передача больших объёмов данных

• GET помещает параметры в URL, который имеет длину ~2000 символов (в большинстве браузеров)
• Если нужно отправить сложный фильтр или JSON body, используй POST (с соглашением: POST для поиска)

Пример (POST для поиска с complex filter):

POST /api/v1/users/search
{
  "filters": {
    "age_min": 18,
    "age_max": 65,
    "cities": ["Moscow", "SPb"],
    "skills": ["Python", "Go"]
  },
  "sort": "last_active_desc"
}

Изменение состояния

• "GET /api/v1/orders/123/mark-as-completed" — НЕПРАВИЛЬНО (это change)
• Нужен "PATCH /api/v1/orders/123" с {"status": "completed"} — ПРАВИЛЬНО

Удаление (очень редко)

• DELETE /api/v1/items/123 — правильно удалить
• GET /api/v1/items/123/delete — неправильно

Ошибки при использовании GET

Ошибка 1: GET для создания

GET /api/v1/users/create?name=Ivan&email=ivan@mail.com

Это нарушает REST. Должен быть POST /api/v1/users с body.

Ошибка 2: Неправильные коды ответов

GET /api/v1/users/999
Ответ 200 OK: { "error": "User not found" }

Правильно: Ответ 404 Not Found с сообщением об ошибке.

Кеширование GET запросов

Одно из больших преимуществ GET — можно кешировать на разных уровнях:

• Browser cache — сохраняет ответ локально
• CDN cache — распределённый кеш на серверах по миру
• Server-side cache — Redis, Memcached

Это позволяет снизить нагрузку и ускорить отклик:

GET /api/v1/products/123
Cache-Control: public, max-age=3600  // Кешировать 1 час

Best Practice для BA

Когда пишешь требования к API:

1. Для чтения данных всегда GET
2. Указывай результаты — формат JSON, обязательные поля
3. Описывай параметры — какие фильтры, сортировка, пагинация
4. Думай про error cases — что если ресурс не найден (404)
5. Указывай коды ответов — 200 OK, 404 Not Found, 401 Unauthorized

Пример спецификации:

GET /api/v1/users/{id}
Параметры:
  - id (path, required): UUID пользователя

Ответ 200:
  { "id": "uuid", "name": "string", "email": "string" }

Ответ 404:
  { "error": "User not found" }

Вывод

ГЕТ — основной инструмент для получения данных. Используй его для:

• Получения одной сущности по ID
• Получения списка с фильтрацией, сортировкой, пагинацией
• Поиска

Это безопасно, идемпотентно, кешируемо и соответствует REST принципам.