Документация API V2

Общие замечания:

• Базовый URL для всех эндпоинтов: /api/v2/.
• Ключевое отличие от V1: Во всех запросах, требующих аутентификации, токен должен передаваться в заголовке Authorization. Формат: Token <ваш_токен>. Токен больше не передается в теле запроса.
• Для запросов типа POST, ожидающих данные в формате JSON, следует использовать заголовок Content-Type: application/json.
• Примеры на Python написаны с использованием библиотеки requests.

1. Аутентификация и Пользователи

1.1. Вход в систему (Login)

POST /api/v2/login/

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

Описание: Аутентифицирует пользователя и возвращает токен доступа. Этот эндпоинт работает так же, как в V1.

Тело запроса (application/json):

{
    "username": "your_username",
    "password": "your_password"
}

Параметр	Тип	Обязательный	Описание
username	string	Да	Имя пользователя.
password	string	Да	Пароль пользователя.

Успешный ответ (200 OK):

{
    "token": "your_auth_token"
}

Пример вызова (Python):

import requests

url = "http://127.0.0.1:8000/api/v2/login/"
data = {"username": "your_username", "password": "your_password"}
response = requests.post(url, json=data)
print(response.json())
        

Ответы с ошибками:

• 404 Not Found:

  { "error": "User not found" }

• 401 Unauthorized:

  { "error": "Invalid credentials" }

1.2. Регистрация (Register)

POST /api/v2/register/

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

Описание: Регистрирует нового пользователя и возвращает токен доступа. Этот эндпоинт работает так же, как в V1.

Тело запроса (application/json):

{
    "username": "new_username",
    "email": "user@example.com",
    "password": "new_password"
}

Параметр	Тип	Обязательный	Описание
username	string	Да	Желаемое имя пользователя.
email	string	Да	Email пользователя.
password	string	Да	Пароль пользователя.

Успешный ответ (200 OK):

{
    "token": "your_auth_token"
}

Пример вызова (Python):

import requests

url = "http://127.0.0.1:8000/api/v2/register/"
data = {"username": "new_username", "email": "user@example.com", "password": "new_password"}
response = requests.post(url, json=data)
print(response.json())
        

Ответы с ошибками:

• 400 Bad Request:

  { "error": "Username already exists" }

  или

  { "error": "Email already exists" }

• 500 Internal Server Error:

  { "error": "Registration failed" }

1.3. Выход из системы (Logout)

POST /api/v2/logout/

Права доступа: Требуется аутентификация по токену.

Описание: Удаляет токен аутентификации, переданный в заголовке, осуществляя выход пользователя.

Заголовки запроса (Headers):

Заголовок	Значение
Authorization	Token your_auth_token

Успешный ответ (200 OK):

{
    "message": "Logged out successfully"
}

Пример вызова (Python):

import requests

token = "your_auth_token"
url = "http://127.0.0.1:8000/api/v2/logout/"
headers = {"Authorization": f"Token {token}"}
response = requests.post(url, headers=headers)
print(response.json())
        

Ответы с ошибками:

• 401 Unauthorized:

  { "error": "Invalid token" }

  или

  { "error": "Authorization header missing" }

1.4. Получение данных текущего пользователя (My Data)

POST /api/v2/my-data/

Права доступа: Требуется аутентификация по токену.

Описание: Возвращает данные пользователя, ассоциированного с токеном в заголовке.

Заголовки запроса (Headers):

Заголовок	Значение
Authorization	Token your_auth_token

Успешный ответ (200 OK):

{
    "id": 1,
    "username": "current_username",
    "email": "user@example.com",
    "avatar": "/media/avatars/avatar.jpg", // или null
    "gender": "male", // или "female", "unspecified"
    "info": "Some info about the user", // или null
    "city": "User City", // или null
    "is_online": true // или false
}

Пример вызова (Python):

import requests

token = "your_auth_token"
url = "http://127.0.0.1:8000/api/v2/my-data/"
headers = {"Authorization": f"Token {token}"}
response = requests.post(url, headers=headers)
print(response.json())
        

Ответы с ошибками:

• 401 Unauthorized:

  { "error": "Invalid token" }

• 404 Not Found:

  { "error": "User data not found" }

1.5. Получение данных другого пользователя (User Data)

GET /api/v2/user-data/<str:username>/

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

Описание: Возвращает публичные данные пользователя по его имени пользователя. Аутентификация не требуется.

Параметры пути:

Параметр	Тип	Обязательный	Описание
username	string	Да	Имя пользователя, чьи данные запрашиваются.

Успешный ответ (200 OK):

{
    "id": 2,
    "username": "other_username",
    "email": "other_user@example.com",
    "avatar": "/media/avatars/other_avatar.jpg", // или null
    "gender": "female", // или "male", "unspecified"
    "info": "Some info about the other user", // или null
    "city": "Other User City", // или null
    "is_online": false // или true
}

Пример вызова (Python):

import requests

username = "target_username"
url = f"http://127.0.0.1:8000/api/v2/user-data/{username}/"
response = requests.get(url)
print(response.json())
        

Ответы с ошибками:

• 404 Not Found:

  { "error": "User not found" }

1.6. Поиск пользователей (Search)

POST /api/v2/search/

Права доступа: Требуется аутентификация по токену.

Описание: Позволяет искать пользователей по имени пользователя (и, возможно, по имени/фамилии). Результаты ограничены 20 пользователями и исключают текущего пользователя.

Заголовки запроса (Headers):

Заголовок	Значение
Authorization	Token your_auth_token

Тело запроса (application/json):

{
    "q": "search_query"
}

Параметр	Тип	Обязательный	Описание
q	string	Да	Поисковый запрос (имя пользователя, часть имени).

Успешный ответ (200 OK):

{
    "users": [
        {
            "id": 1,
            "username": "found_user1",
            "avatar": "/media/avatars/user1.jpg", // или null
            "is_online": true, // или false, если доступно
            "first_name": "First", // если доступно
            "last_name": "Last" // если доступно
        },
        // ... другие найденные пользователи
    ],
    "query": "search_query"
}

Пример вызова (Python):

import requests

token = "your_auth_token"
url = "http://127.0.0.1:8000/api/v2/search/"
headers = {"Authorization": f"Token {token}"}
data = {"q": "testuser"}
response = requests.post(url, json=data, headers=headers)
print(response.json())
        

Ответы с ошибками:

• 400 Bad Request:

  { "error": "Search query \"q\" is required in the request body." }

• 401 Unauthorized:

  { "error": "Invalid token" }

2. Чаты и Сообщения

2.1. Список чатов пользователя (Chats)

POST /api/v2/chats/

Права доступа: Требуется аутентификация по токену.

Описание: Возвращает список чатов текущего пользователя, отсортированных по времени последнего сообщения.

Заголовки запроса (Headers):

Заголовок	Значение
Authorization	Token your_auth_token

Успешный ответ (200 OK):

Массив объектов чатов. Каждый объект чата имеет следующую структуру:

[
    {
        "id": 1, // ID чата
        "user1": { // Данные первого участника чата
            "id": 10,
            "username": "user1_username",
            "avatar": "/media/avatars/user1.jpg",
            "current_user": true // true, если это текущий пользователь
        },
        "user2": { // Данные второго участника чата
            "id": 12,
            "username": "user2_username",
            "avatar": "/media/avatars/user2.jpg",
            "current_user": false
        },
        "last_message": { // Последнее сообщение в чате
            "id": 101,
            "text": "Hello there!",
            "photo": null,
            "created_at": "10:30, 01.01.2023",
            "user": {
                "username": "user1_username",
                "avatar": "/media/avatars/user1.jpg"
            }
        } // или null, если сообщений нет
    },
    // ... другие чаты
]

Пример вызова (Python):

import requests

token = "your_auth_token"
url = "http://127.0.0.1:8000/api/v2/chats/"
headers = {"Authorization": f"Token {token}"}
response = requests.post(url, headers=headers)
print(response.json())
        

Ответы с ошибками:

• 401 Unauthorized:

  { "error": "Invalid token" }

• 500 Internal Server Error:

  { "error": "Сообщение об ошибке сервера" }

2.2. Сообщения в чате (Chat Messages)

POST /api/v2/chat/<int:chat_id>/

Права доступа: Требуется аутентификация по токену.

Описание: Возвращает все сообщения из указанного чата, если текущий пользователь является его участником. Сообщения отсортированы по времени создания.

Параметры пути:

Параметр	Тип	Обязательный	Описание
chat_id	integer	Да	ID чата, сообщения которого запрашиваются.

Заголовки запроса (Headers):

Заголовок	Значение
Authorization	Token your_auth_token

Успешный ответ (200 OK):

Массив объектов сообщений. Каждый объект сообщения имеет следующую структуру:

[
    {
        "id": 1, // ID сообщения
        "text": "First message text", // или null, если только фото
        "photo": "/media/chat_photos/image.jpg", // или null, если только текст
        "created_at": "09:00, 01.01.2023", // Время создания в формате ЧЧ:ММ, ДД.ММ.ГГГГ
        "user": {
            "username": "sender_username",
            "avatar": "/media/avatars/sender_avatar.jpg" // или null
        }
    },
    // ... другие сообщения
]

Пример вызова (Python):

import requests

token = "your_auth_token"
chat_id = 1
url = f"http://127.0.0.1:8000/api/v2/chat/{chat_id}/"
headers = {"Authorization": f"Token {token}"}
response = requests.post(url, headers=headers)
print(response.json())
        

Ответы с ошибками:

• 401 Unauthorized:

  { "error": "Invalid token" }

• 403 Forbidden:

  { "error": "You are not a participant in this chat" }

• 404 Not Found:

  { "error": "Chat room not found" }

• 500 Internal Server Error:

  { "error": "Сообщение об ошибке сервера" }