📖 API Guide - SkiTrip Journal

Полное руководство по использованию REST API проекта SkiTrip Journal.

🔗 Базовый URL

Production: https://snowlog.ru/api/
Local:      http://localhost:8000/api/

📚 Содержание

Аутентификация
Курорты
Поездки
Медиафайлы
Пользователи
Коды ответов

🔐 Аутентификация

API использует JWT (JSON Web Tokens) для аутентификации.

Получение токенов:

Endpoint: POST /api/auth/token/

Request:

{
  "username": "testuser",
  "password": "testuser"
}

Response (200 OK):

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Время жизни:

Access токен: 15 минут
Refresh токен: 7 дней

Обновление токена:

Endpoint: POST /api/auth/token/refresh/

Request:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Response (200 OK):

{
  "access": "новый_access_токен...",
  "refresh": "новый_refresh_токен..."
}

Использование токена:

Добавь заголовок Authorization в каждый запрос:

Authorization: Bearer

Пример (curl):

curl http://localhost:8000/api/trips/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Q..."

🏔️ Курорты

Список всех курортов:

Endpoint: GET /api/resorts/

Параметр	Тип	Описание	Пример
`search`	string	Поиск по названию, региону, описанию	`?search=Роза`
`region`	string	Фильтр по региону (частичное совпадение)	`?region=Урал`
`name`	string	Фильтр по названию (частичное совпадение)	`?name=Шереге`
`ordering`	string	Сортировка	`?ordering=name` или `?ordering=-region`
`page`	integer	Номер страницы	`?page=2`

Примеры запросов:

# Все курорты
GET /api/resorts/

# Поиск "Роза"
GET /api/resorts/?search=Роза

# Курорты Свердловской области
GET /api/resorts/?region=Свердловская

# Сортировка по алфавиту
GET /api/resorts/?ordering=name

# Комбинация
GET /api/resorts/?region=Краснодарский&ordering=name

Response (200 OK):

{
  "count": 15,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 8,
      "name": "Абзаково",
      "slug": "abzakovo",
      "region": "Республика Башкортостан",
      "description": "Крупнейший курорт Урала ...",
      "created_at": "2025-12-24T15:31:04.771000+05:00"
    },
    {
      "id": 4,
      "name": "Архыз",
      "slug": "arkhyz",
      "region": "Карачаево-Черкесская Республика",
      "description": "Молодой курорт в Западном Кавказе ...",
      "created_at": "2025-12-24T15:31:04.771000+05:00"
    }
  ]
}

Детали курорта:

Endpoint: GET /api/resorts/{slug}/

Пример:

GET /api/resorts/roza-hutor/

Response (200 OK):

{
  "id": 1,
  "name": "Роза Хутор",
  "slug": "roza-khutor",
  "region": "Краснодарский край, Красная Поляна",
  "description": "Крупнейший горнолыжный курорт России ...",
  "created_at": "2025-12-24T15:31:04.771000+05:00"
}

Ошибки:

404 Not Found - курорт с указанным slug не найден

Поездки на курорт:

Endpoint: GET /api/resorts/{slug}/trips/

Права доступа:

Гость: видит только публичные поездки
Авторизованный: видит публичные поездки всех пользователей + свои приватные

Пример:

GET /api/resorts/roza-hutor/trips/

Response (200 OK):

[
  {
    "id": 1,
    "user": "testuser",
    "resort": {
      "id": 1,
      "name": "Роза Хутор",
      "slug": "roza-hutor",
      "region": "Краснодарский край",
      "description": "Крупнейший горнолыжный курорт России ...",
      "created_at": "2025-12-24T15:31:04.771000+05:00"
    },
    "start_date": "2024-01-10",
    "end_date": "2024-01-17",
    "comment": "Отличная поездка на Розу Хутор ...",
    "is_public": true,
    "created_at": "2024-01-20T15:00:00+05:00"
  }
]

Ошибки:

404 Not Found - курорт не найден

🎿 Поездки

Список поездок:

Endpoint: GET /api/trips/

Права доступа:

Гость: видит только публичные поездки
Авторизованный: видит публичные поездки всех + свои приватные

Параметр	Тип	Описание	Пример
`is_public`	boolean	Только публичные/приватные	`?is_public=true`
`resort_id`	integer	ID курорта	`?resort_id=1`
`resort_region`	string	Регион курорта (частичное)	`?resort_region=Урал`
`start_date_from`	date	Дата начала (от)	`?start_date_from=2024-01-01`
`start_date_to`	date	Дата начала (до)	`?start_date_to=2024-12-31`
`end_date_from`	date	Дата окончания (от)	`?end_date_from=2024-01-01`
`end_date_to`	date	Дата окончания (до)	`?end_date_to=2024-12-31`
`search`	string	Поиск по названию курорта, региону, комментарию	`?search=снег`
`ordering`	string	Сортировка	`?ordering=-start_date`
`page`	integer	Номер страницы	`?page=2`

Примеры запросов:

# Все публичные поездки
GET /api/trips/?is_public=true

# Поездки на Розу Хутор
GET /api/trips/?resort_id=1

# Поездки в Свердловскую область
GET /api/trips/?resort_region=Свердловская

# Поездки после 1 января 2024
GET /api/trips/?start_date_from=2024-01-01

# Поездки в диапазоне дат
GET /api/trips/?start_date_from=2024-01-01&start_date_to=2024-03-31

# Комбинация фильтров + сортировка
GET /api/trips/?is_public=true&resort_region=Свердловская&ordering=-start_date

# Поиск по комментарию
GET /api/trips/?search=снег

Response (200 OK):

{
  "count": 15,
  "next": "http://localhost:8000/api/trips/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "user": "testuser",
      "resort": {
        "id": 1,
        "name": "Роза Хутор",
        "slug": "roza-hutor",
        "region": "Краснодарский край",
        "description": "...",
        "created_at": "2025-12-24T15:31:04.771000+05:00"
      },
      "start_date": "2024-01-10",
      "end_date": "2024-01-17",
      "comment": "Отличная поездка на Розу Хутор ...",
      "is_public": true,
      "created_at": "2024-01-20T15:00:00+05:00"
    }
  ]
}

Детали поездки:

Endpoint: GET /api/trips/{id}/

Права доступа:

Гость: только публичные поездки
Авторизованный: публичные + свои приватные

Пример:

GET /api/trips/5/

Response (200 OK):

{
  "id": 5,
  "user": "testuser",
  "resort": {
    "id": 3,
    "name": "Красная Поляна (Газпром)",
    "slug": "krasnaya-polyana-gazprom",
    "region": "Краснодарский край, Красная Поляна",
    "description": "Современный всесезонный курорт с развитой инфраструктурой. Перепад высот 1428 м, 30 км трасс. Включает зоны Альпика, Лаура и Горки Город. Подходит для семейного отдыха. Сезон: декабрь-апрель.",
    "created_at": "2025-12-24T15:31:04.771000+05:00"
  },
  "start_date": "2024-02-14",
  "end_date": "2024-02-18",
  "comment": "Красная Поляна на День Святого Валентина. Романтично и активно! Отличные условия на трассах.",
  "is_public": true,
  "created_at": "2024-02-20T16:00:00+05:00"
}

Ошибки:

404 Not Found - поездка не найдена или не доступна (приватная поездка другого пользователя)

Создание поездки:

Endpoint: POST /api/trips/

Требуется: JWT токен (аутентификация)

Request:

{
  "resort": 1,
  "start_date": "2026-06-01",
  "end_date": "2026-06-07",
  "comment": "Планируем поездку летом",
  "is_public": true
}

Response (201 Created):

{
  "id": 16,
  "user": "testuser",
  "resort": {
    "id": 1,
    "name": "Роза Хутор",
    "...": "..."
  },
  "start_date": "2026-06-01",
  "end_date": "2026-06-07",
  "comment": "Планируем поездку летом",
  "is_public": true,
  "created_at": "2026-02-10T15:30:00Z"
}

Ошибки:

401 Unauthorized - токен не предоставлен или невалиден
400 Bad Request - невалидные данные (например, start_date > end_date)

Обновление поездки (полное):

Endpoint: PUT /api/trips/{id}/

Требуется: Владелец поездки (JWT токен)

Request (все поля обязательны):

{
  "resort": 1,
  "start_date": "2024-06-01",
  "end_date": "2024-06-10",
  "comment": "Продлили поездку на 3 дня!",
  "is_public": true
}

Response (200 OK): обновлённая поездка

Ошибки:

401 Unauthorized - не авторизован
403 Forbidden - это не ваша поездка
400 Bad Request - невалидные данные
404 Not Found - поездка не найдена

Обновление поездки (частичное):

Endpoint: PATCH /api/trips/{id}/

Требуется: Владелец поездки (JWT токен)

Request (только изменяемые поля):

{
  "is_public": false
}

Response (200 OK): обновлённая поездка

Ошибки: те же, что у PUT

Удаление поездки:

Endpoint: DELETE /api/trips/{id}/

Требуется: Владелец поездки (JWT токен)

Response (204 No Content): пустое тело

Ошибки:

401 Unauthorized - не авторизован
403 Forbidden - это не ваша поездка
404 Not Found - поездка не найдена

📸 Медиафайлы

Список всех медиафайлов:

Endpoint: GET /api/media/

Права доступа:

Гость: медиа публичных поездок
Авторизованный: медиа публичных + своих приватных поездок

Response (200 OK):

{
  "count": 11,
  "next": "http://localhost:8000/api/media/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "trip": 1,
      "image": "http://localhost:8000/media/trip_photos/roza_khutor_1.jpg",
      "uploaded_at": "2024-01-20T15:05:00+05:00"
    }
  ]
}

Фотографии поездки:

Endpoint: GET /api/trips/{id}/media/

Права доступа: зависят от доступа к самой поездке

Пример:

GET /api/trips/5/media/

Response (200 OK):

[
  {
    "id": 7,
    "trip": 5,
    "image": "http://localhost:8000/media/trip_photos/krasnaya_polyana_1.jpg",
    "uploaded_at": "2024-02-20T16:05:00+05:00"
  },
  {
    "id": 8,
    "trip": 5,
    "image": "http://localhost:8000/media/trip_photos/krasnaya_polyana_2.jpg",
    "uploaded_at": "2024-02-20T16:06:00+05:00"
  }
]

Ошибки:

404 Not Found - поездка не найдена или недоступна

Детали медиафайла:

Endpoint: GET /api/media/{id}/

Пример:

GET /api/media/12/

Response (200 OK):

{
  "id": 12,
  "trip": 8,
  "image": "http://localhost:8000/media/trip_photos/manzherok.jpg",
  "uploaded_at": "2024-02-26T15:20:00+05:00"
}

👤 Пользователи

Список пользователей:

Endpoint: GET /api/users/

Права доступа: доступно всем

Response (200 OK):

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "username": "testuser",
      "date_joined": "2024-01-01T15:00:00+05:00",
      "trips_count": 5
    },
    {
      "id": 2,
      "username": "anotheruser",
      "date_joined": "2024-01-05T12:30:00Z",
      "trips_count": 5
    }
  ]
}

Примечание: trips_count - количество публичных поездок пользователя.

Профиль пользователя:

Endpoint: GET /api/users/{id}/

Пример:

GET /api/users/1/

Response (200 OK):

{
  "id": 1,
  "username": "testuser",
  "date_joined": "2024-01-01T10:00:00Z",
  "trips_count": 5
}

Ошибки:

404 Not Found - пользователь не найден

Поездки пользователя:

Endpoint: GET /api/users/{id}/trips/

Возвращает: только публичные поездки пользователя

Response (200 OK):

[
  {
    "id": 1,
    "user": "testuser",
    "resort": {
      "id": 1,
      "name": "Роза Хутор",
      "...": "..."
    },
    "start_date": "2024-01-10",
    "end_date": "2024-01-17",
    "comment": "Отличная поездка ...",
    "is_public": true,
    "created_at": "2024-01-20T15:00:00+05:00"
  }
]

Ошибки:

404 Not Found - пользователь не найден

📊 Коды ответов

Код	Значение	Описание
`200 OK`	Успешно	Запрос выполнен успешно
`201 Created`	Создано	Объект успешно создан
`204 No Content`	Нет содержимого	Объект успешно удалён (тело ответа пустое)
`400 Bad Request`	Неверный запрос	Невалидные данные в запросе
`401 Unauthorized`	Не авторизован	Требуется аутентификация (токен не предоставлен или истёк)
`403 Forbidden`	Запрещено	Нет прав доступа (не владелец ресурса)
`404 Not Found`	Не найдено	Запрашиваемый ресурс не существует
`405 Method Not Allowed`	Метод не разрешён	HTTP метод не поддерживается для этого эндпоинта
`500 Internal Server Error`	Внутренняя ошибка	Ошибка на сервере

🔗 Полезные ссылки

Swagger UI (интерактивная документация): https://snowlog.ru/api/docs/
ReDoc (альтернативная документация): https://snowlog.ru/api/redoc/
OpenAPI схема (JSON): https://snowlog.ru/api/schema/
GitHub репозиторий: https://github.com/dmitriy347/MountainTrip
Основной сайт: https://snowlog.ru

FilesExpand file tree

API_GUIDE.md

Latest commit

History

API_GUIDE.md

File metadata and controls

📖 API Guide - SkiTrip Journal

🔗 Базовый URL

📚 Содержание

🔐 Аутентификация

Получение токенов:

Обновление токена:

Использование токена:

🏔️ Курорты

Список всех курортов:

Детали курорта:

Поездки на курорт:

🎿 Поездки

Список поездок:

Детали поездки:

Создание поездки:

Обновление поездки (полное):

Обновление поездки (частичное):

Удаление поездки:

📸 Медиафайлы

Список всех медиафайлов:

Фотографии поездки:

Детали медиафайла:

👤 Пользователи

Список пользователей:

Профиль пользователя:

Поездки пользователя:

📊 Коды ответов

🔗 Полезные ссылки