Справочник организаций (REST API)

Сервис предоставляет API для работы со справочником:

• организаций
• зданий
• видов деятельности (дерево до 3 уровней вложенности)

Технологии

• FastAPI
• Pydantic v2
• SQLAlchemy 2
• Alembic
• SQLite
• Docker / Docker Compose

Что реализовано

• Авторизация по статическому API-ключу в заголовке X-API-Key.
• Все ответы в формате JSON.
• Ограничение вложенности деятельностей до 3 уровней (на уровне схемы БД).
• Миграция Alembic для создания таблиц и наполнения тестовыми данными.
• Документация API через Swagger UI и ReDoc.

Функциональность API

Базовый префикс: /api/v1

• GET /buildings - список зданий.
• GET /buildings/{building_id}/organizations - организации в конкретном здании.
• GET /activities - список видов деятельности.
• GET /activities/tree - дерево видов деятельности.
• GET /activities/{activity_id}/organizations?include_descendants=false - организации по виду деятельности.
• GET /organizations/{organization_id} - карточка организации по идентификатору.
• GET /organizations/search/by-name?name=milk - поиск организаций по названию.
• GET /organizations/search/by-activity/{activity_id}?include_descendants=true - поиск по виду деятельности с учетом дочерних.
• GET /organizations/search/radius?latitude=55.75&longitude=37.61&radius_km=5 - поиск в радиусе от точки.
• GET /organizations/search/rectangle?min_lat=55.7&max_lat=55.8&min_lon=37.5&max_lon=37.7 - поиск в прямоугольной области.

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

После запуска приложения:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

Чтобы выполнять запросы в Swagger:

1. Нажмите Authorize.
2. В поле X-API-Key укажите значение dev-static-api-key.

Быстрый старт (Docker, рекомендуется)

docker compose up --build

Приложение внутри контейнера автоматически применяет миграции перед стартом сервера.

Остановка:

docker compose down

Локальный запуск (без Docker)

1. Установите зависимости:

pip install -r requirements.txt

2. Создайте файл окружения:

cp .env.example .env

3. Примените миграции:

alembic upgrade head

4. Запустите API:

uvicorn app.main:app --reload

Переменные окружения

Файл .env.example:

API_KEY=dev-static-api-key
DATABASE_URL=sqlite+aiosqlite:///./app.db
API_PREFIX=/api/v1

• API_KEY - статический ключ доступа к API.
• DATABASE_URL - строка подключения к БД.
• API_PREFIX - базовый префикс для маршрутов API.

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

Список зданий:

curl -H "X-API-Key: dev-static-api-key" http://127.0.0.1:8000/api/v1/buildings

Поиск организаций по названию:

curl -H "X-API-Key: dev-static-api-key" "http://127.0.0.1:8000/api/v1/organizations/search/by-name?name=Milk"

Поиск по деятельности с дочерними категориями:

curl -H "X-API-Key: dev-static-api-key" "http://127.0.0.1:8000/api/v1/organizations/search/by-activity/1?include_descendants=true"

Структура проекта

app/
  api/
    routes/
  core/
  db/
  models/
  schemas/
  services/
alembic/
  versions/