feat: add api version

Author: volychev

README.md

@@ -12,7 +12,7 @@
 │   └── workflows
 │       └── ci.yml
 ├── telemetry_api                    
-│   ├── api                          # Основные роутеры 
+│   ├── api/v1                       # Основные роутеры 
 │   │   ├── __init__.py              # Инициализация FastAPI и подключение роутеров
 │   │   ├── analytics.py
 │   │   ├── devices.py
@@ -50,24 +50,27 @@
 ```
 
 ## Endpoints:
-* `POST`: `/users/` — Создание нового пользователя
-* `GET`: `/users/{user_id}` — Получение пользователя по id
-* `PATCH`: `/users/{user_id}` — Частичное обновление данных пользователя
-* `DELETE`: `/users/{user_id}` — Удаление пользователя
-* `GET`: `/users/` — Получение списка пользователей с пагинацией
+Базовый префикс API: `/api`
+Текущая версия: `/v1`
+
+* `POST`: `/api/v1/users/` — Создание нового пользователя
+* `GET`: `/api/v1/users/{user_id}` — Получение пользователя по id
+* `PATCH`: `/api/v1/users/{user_id}` — Частичное обновление данных пользователя
+* `DELETE`: `/api/v1/users/{user_id}` — Удаление пользователя
+* `GET`: `/api/v1/users/` — Получение списка пользователей с пагинацией
 <br>
 
-* `POST`: `/devices/` — Создание нового устройства (с возможностью привязки к пользователю)
-* `GET`: `/devices/{device_id}` — Получение устройства по id
-* `PATCH`: `/devices/{device_id}` — Частичное обновление данных устройства (включая смену владельца)
-* `DELETE`: `/devices/{device_id}` — Удаление устройства
-* `GET`: `/devices/` — Получение списка устройств с пагинацией
+* `POST`: `/api/v1/devices/` — Создание нового устройства (с возможностью привязки к пользователю)
+* `GET`: `/api/v1/devices/{device_id}` — Получение устройства по id
+* `PATCH`: `/api/v1/devices/{device_id}` — Частичное обновление данных устройства (включая смену владельца)
+* `DELETE`: `/api/v1/devices/{device_id}` — Удаление устройства
+* `GET`: `/api/v1/devices/` — Получение списка устройств с пагинацией
 <br>
 
-* `POST`: `/analytics/{device_id}/data` — Добавление одного измерения для конкретного устройства
-* `GET`: `/analytics/` — Получение агрегированной аналитики по устройству или пользователю (с возможностью фильтрации по времени и пагинацией)
-* `POST`: `/analytics/generate` — Запуск фоновой задачи через Celery для генерации аналитики асинхронно
-* `GET`: `/analytics/tasks/{task_id}` — Получение статуса или готового (пагинированного) результата фоновой задачи генерации аналитики
+* `POST`: `/api/v1/analytics/{device_id}/data` — Добавление одного измерения для конкретного устройства
+* `GET`: `/api/v1/analytics/` — Получение агрегированной аналитики по устройству или пользователю (с возможностью фильтрации по времени и пагинацией)
+* `POST`: `/api/v1/analytics/generate` — Запуск фоновой задачи через Celery для генерации аналитики асинхронно
+* `GET`: `/api/v1/analytics/tasks/{task_id}` — Получение статуса или готового (пагинированного) результата фоновой задачи генерации аналитики
 <br>
 
 * `GET`: `/docs/` — Подробная документация с описанием нетривиальных функций и примерами данных

locustfile.py

@@ -2,6 +2,10 @@
 
 from locust import HttpUser, between, task
 
+API_PREFIX = "/api"
+API_VERSION = "v1"
+API_ROOT = f"{API_PREFIX}/{API_VERSION}"
+
 
 class TelemetryApiUser(HttpUser):
     wait_time = between(0.5, 3.0)
@@ -19,9 +23,9 @@ def _create_user(self) -> int:
         }
 
         with self.client.post(
-            "/users/",
+            f"{API_ROOT}/users/",
             json=payload,
-            name="POST /users/",
+            name=f"POST {API_ROOT}/users/",
             catch_response=True
         ) as response:
             if response.status_code != 201:
@@ -38,9 +42,9 @@ def _create_device(self, user_id: int) -> int:
         }
 
         with self.client.post(
-            "/devices/",
+            f"{API_ROOT}/devices/",
             json=payload,
-            name="POST /devices/",
+            name=f"POST {API_ROOT}/devices/",
             catch_response=True
         ) as response:
             if response.status_code != 201:
@@ -58,9 +62,9 @@ def _add_measurement(self, device_id: int):
         }
 
         with self.client.post(
-            f"/analytics/{device_id}/data",
+            f"{API_ROOT}/analytics/{device_id}/data",
             json=payload,
-            name="POST /analytics/{device_id}/data",
+            name=f"POST {API_ROOT}/analytics/{device_id}/data",
             catch_response=True,
         ) as response:
             if response.status_code != 201:
@@ -78,7 +82,12 @@ def get_device_analytics(self):
             "offset": 0,
         }
 
-        with self.client.get("/analytics/", params=params, name="GET /analytics/?device_id", catch_response=True) as response:
+        with self.client.get(
+            f"{API_ROOT}/analytics/",
+            params=params,
+            name=f"GET {API_ROOT}/analytics/?device_id",
+            catch_response=True
+        ) as response:
             if response.status_code != 200:
                 response.failure(f"Unexpected status: {response.status_code}, body={response.text}")
                 return
@@ -90,9 +99,9 @@ def get_device_analytics(self):
     @task(2)
     def get_users(self):
         with self.client.get(
-            "/users/",
+            f"{API_ROOT}/users/",
             params={"limit": 10, "offset": 0},
-            name="GET /users/",
+            name=f"GET {API_ROOT}/users/",
             catch_response=True,
         ) as response:
             if response.status_code != 200:
@@ -101,9 +110,9 @@ def get_users(self):
     @task(2)
     def get_devices(self):
         with self.client.get(
-            "/devices/",
+            f"{API_ROOT}/devices/",
             params={"limit": 10, "offset": 0},
-            name="GET /devices/",
+            name=f"GET {API_ROOT}/devices/",
             catch_response=True,
         ) as response:
             if response.status_code != 200:

telemetry_api/api/__init__.py

@@ -1,6 +1,7 @@
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI
 
-from telemetry_api.api import analytics, devices, users
+from telemetry_api.api.v1 import analytics, devices, users
+from telemetry_api.config import config
 
 
 def create_api() -> FastAPI:
@@ -11,12 +12,18 @@ def create_api() -> FastAPI:
     api = FastAPI(
         title="Telemetry API",
         description="",
-        version="1.0.0"
+        version="1.0.0",
     )
 
-    api.include_router(analytics.router)
-    api.include_router(devices.router)
-    api.include_router(users.router)
+    api_router = APIRouter(prefix=config.api_prefix.rstrip("/"))
+    v1_router = APIRouter(prefix=f"/{config.default_api_version.strip('/')}")
+
+    v1_router.include_router(analytics.router)
+    v1_router.include_router(devices.router)
+    v1_router.include_router(users.router)
+
+    api_router.include_router(v1_router)
+    api.include_router(api_router)
     return api
 
 

telemetry_api/api/analytics.py telemetry_api/api/v1/analytics.pytelemetry_api/api/analytics.py renamed to telemetry_api/api/v1/analytics.py

@@ -8,6 +8,8 @@ class Settings(BaseSettings):
     host: str = "0.0.0.0"
     port: int = 8000
     celery_result_expires: int = 12 * 60 * 60
+    api_prefix: str = "/api"
+    default_api_version: str = "v1"
 
     postgres_user: SecretStr
     postgres_password: SecretStr
@@ -27,7 +29,7 @@ class Settings(BaseSettings):
 
 
 @lru_cache
-def get_config() -> BaseSettings:
+def get_config() -> Settings:
     return Settings()
 
 

telemetry_api/api/devices.py telemetry_api/api/v1/devices.pytelemetry_api/api/devices.py renamed to telemetry_api/api/v1/devices.py

@@ -47,3 +47,13 @@ async def async_client():
 
     async with AsyncClient(transport=transport, base_url="https://example.com") as client:
         yield client
+
+
+API_PREFIX = "/api"
+API_VERSION = "v1"
+API_ROOT = f"{API_PREFIX}/{API_VERSION}"
+
+
+def api_path(path: str) -> str:
+    normalized_path = path if path.startswith("/") else f"/{path}"
+    return f"{API_ROOT}{normalized_path}"

telemetry_api/api/users.py telemetry_api/api/v1/users.pytelemetry_api/api/users.py renamed to telemetry_api/api/v1/users.py

@@ -1,17 +1,19 @@
 from httpx import AsyncClient
 
+from conftest import api_path
+
 
 async def _create_user(async_client: AsyncClient) -> int:
     response = await async_client.post(
-        "/users/",
+        api_path("/users/"),
         json={"username": "kirill", "email": "kirill@example.com"},
     )
     return response.json()["id"]
 
 
 async def _create_device(async_client: AsyncClient, name: str, user_id: int) -> int:
     response = await async_client.post(
-        "/devices/",
+        api_path("/devices/"),
         json={"name": name, "user_id": user_id},
     )
     return response.json()["id"]
@@ -27,10 +29,8 @@ async def test_add_measurement(async_client: AsyncClient):
     user_id = await _create_user(async_client)
     device_id = await _create_device(async_client, "Analytics Device", user_id)
 
-    response = await async_client.post(
-        f"/analytics/{device_id}/data",
-        json={"x": 1.5, "y": 2.5, "z": 3.5},
-    )
+    analytics_url = api_path("/analytics/").rstrip("/")
+    response = await async_client.post(f"{analytics_url}/{device_id}/data", json={"x": 1.5, "y": 2.5, "z": 3.5})
 
     assert response.status_code == 201
     data = response.json()
@@ -49,10 +49,8 @@ async def test_add_measurement_device_not_found(async_client: AsyncClient):
     Ожидает код 404 при обращении к отсутствующему объекту.
     """
 
-    response = await async_client.post(
-        "/analytics/999999/data",
-        json={"x": 1.0, "y": 2.0, "z": 3.0},
-    )
+    analytics_url = api_path("/analytics/").rstrip("/")
+    response = await async_client.post(f"{analytics_url}/999999/data", json={"x": 1.0, "y": 2.0, "z": 3.0})
 
     assert response.status_code == 404
 
@@ -67,17 +65,12 @@ async def test_get_analytics_by_device(async_client: AsyncClient):
     user_id = await _create_user(async_client)
     device_id = await _create_device(async_client, "Analytics Reader Device", user_id)
 
-    await async_client.post(
-        f"/analytics/{device_id}/data",
-        json={"x": 1.0, "y": 2.0, "z": 3.0}
-    )
-    await async_client.post(
-        f"/analytics/{device_id}/data",
-        json={"x": 3.0, "y": 4.0, "z": 5.0}
-    )
+    analytics_url = api_path("/analytics/").rstrip("/")
+    await async_client.post(f"{analytics_url}/{device_id}/data", json={"x": 1.0, "y": 2.0, "z": 3.0})
+    await async_client.post(f"{analytics_url}/{device_id}/data", json={"x": 3.0, "y": 4.0, "z": 5.0})
 
     response = await async_client.get(
-        "/analytics/",
+        api_path("/analytics/"),
         params={"device_id": device_id, "limit": 25, "offset": 0},
     )
 
@@ -107,15 +100,16 @@ async def test_get_analytics_by_user_uses_stable_pagination(async_client: AsyncC
     first_device_id = await _create_device(async_client, "Device A", user_id)
     second_device_id = await _create_device(async_client, "Device B", user_id)
 
-    await async_client.post(f"/analytics/{first_device_id}/data", json={"x": 1.0, "y": 1.0, "z": 1.0})
-    await async_client.post(f"/analytics/{second_device_id}/data", json={"x": 2.0, "y": 2.0, "z": 2.0})
+    analytics_url = api_path("/analytics/").rstrip("/")
+    await async_client.post(f"{analytics_url}/{first_device_id}/data", json={"x": 1.0, "y": 1.0, "z": 1.0})
+    await async_client.post(f"{analytics_url}/{second_device_id}/data", json={"x": 2.0, "y": 2.0, "z": 2.0})
 
     first_page_response = await async_client.get(
-        "/analytics/",
+        api_path("/analytics/"),
         params={"user_id": user_id, "limit": 1, "offset": 0},
     )
     second_page_response = await async_client.get(
-        "/analytics/",
+        api_path("/analytics/"),
         params={"user_id": user_id, "limit": 1, "offset": 1},
     )
 
@@ -138,7 +132,7 @@ async def test_get_analytics_requires_filter(async_client: AsyncClient):
     Ожидает ошибку 400 при отсутствии обязательного фильтра запроса.
     """
 
-    response = await async_client.get("/analytics/")
+    response = await async_client.get(api_path("/analytics/"))
     assert response.status_code == 400
 
 
@@ -150,7 +144,7 @@ async def test_get_analytics_validates_limit_and_offset(async_client: AsyncClien
     """
 
     response = await async_client.get(
-        "/analytics/",
+        api_path("/analytics/"),
         params={"device_id": 1, "limit": 0, "offset": -1},
     )
 
@@ -164,6 +158,6 @@ async def test_generate_analytics_route_not_conflicting(async_client: AsyncClien
     Ожидает бизнес-ошибку фильтров, а не парсинг `generate` как `device_id`.
     """
 
-    response = await async_client.post("/analytics/generate")
+    response = await async_client.post(api_path("/analytics/generate"))
 
     assert response.status_code == 400

telemetry_api/config.py

@@ -1,17 +1,19 @@
 from httpx import AsyncClient
 
+from conftest import api_path
+
 
 async def _create_user(async_client: AsyncClient) -> int:
     response = await async_client.post(
-        "/users/",
+        api_path("/users/"),
         json={"username": "kirill", "email": "kirill@example.com"},
     )
     return response.json()["id"]
 
 
 async def _create_device(async_client: AsyncClient, name: str, user_id: int | None) -> dict:
     response = await async_client.post(
-        "/devices/",
+        api_path("/devices/"),
         json={"name": name, "user_id": user_id},
     )
 
@@ -58,7 +60,8 @@ async def test_get_device(async_client: AsyncClient):
     owner_id = await _create_user(async_client)
     device = await _create_device(async_client, "Humidity Sensor", owner_id)
 
-    response = await async_client.get(f"/devices/{device['id']}")
+    devices_url = api_path("/devices/").rstrip("/")
+    response = await async_client.get(f"{devices_url}/{device['id']}")
 
     assert response.status_code == 200
     assert response.json()["name"] == "Humidity Sensor"
@@ -75,10 +78,8 @@ async def test_update_device(async_client: AsyncClient):
     owner_id = await _create_user(async_client)
     device = await _create_device(async_client, "Old Sensor Name", owner_id)
 
-    update_response = await async_client.patch(
-        f"/devices/{device['id']}",
-        json={"name": "New Sensor Name"},
-    )
+    devices_url = api_path("/devices/").rstrip("/")
+    update_response = await async_client.patch(f"{devices_url}/{device['id']}", json={"name": "New Sensor Name"})
     updated_device = update_response.json()
 
     assert update_response.status_code == 200
@@ -96,10 +97,11 @@ async def test_delete_device(async_client: AsyncClient):
     owner_id = await _create_user(async_client)
     device = await _create_device(async_client, "Sensor to Delete", owner_id)
 
-    delete_response = await async_client.delete(f"/devices/{device['id']}")
+    devices_url = api_path("/devices/").rstrip("/")
+    delete_response = await async_client.delete(f"{devices_url}/{device['id']}")
     assert delete_response.status_code == 204
 
-    response = await async_client.get(f"/devices/{device['id']}")
+    response = await async_client.get(f"{devices_url}/{device['id']}")
     assert response.status_code == 404
 
 
@@ -116,11 +118,11 @@ async def test_paginate_device(async_client: AsyncClient):
     second_device = await _create_device(async_client, "Paginated Sensor 2", owner_id)
 
     first_response = await async_client.get(
-        "/devices/",
+        api_path("/devices/"),
         params={"limit": 1, "offset": 0},
     )
     second_response = await async_client.get(
-        "/devices/",
+        api_path("/devices/"),
         params={"limit": 1, "offset": 1},
     )