org-handbook-api

Org-Handbook-API — это современный асинхронный RESTful API для управления справочником организаций с расширенными возможностями поиска и геолокации.

Быстрый старт

Предварительные требования

• Docker & Docker Compose
• Git

Установка и запуск

1. Клонирование репозитория

   git clone https://github.com/alexeev-prog/org-handbook-api.git
   cd org-handbook-api

2. Запуск приложения

   docker-compose up --build -d

3. Проверка работоспособности

   curl -H "X-API-Key: secret-static-api-key" http://localhost:8000/health

4. Доступ к документации API
   Откройте в браузере: http://localhost:8000/docs

Утилита для автоматизации

Запустите main.py, если хотите протестировать API, заполнить тестовыми данными или осуществлять взаимодействие через скрипт:

 $ python3 main.py

Usage: main.py [OPTIONS] COMMAND [ARGS]...

Options:
  --base-url TEXT  Base API URL
  --api-key TEXT   API Key
  --help           Show this message and exit.

Commands:
  activities
  buildings
  health
  organizations
  seed

• --base-url - базовый URL запущенного API (например http://0.0.0.0:8000)
• --api-key - статичный токен (по умолчанию secret-static-api-key)
• activities - манипуляции с видами деятельности
• buildings - манипуляции с видами зданий
• health - проверка работы сервера
• organizations - манипуляция с организациями
• seed - заполнение тестовыми данными

Модели данных

Организация (Organization)

{
    "id": 1,
    "legal_name": "ООО Рога и Копыта",
    "building_id": 1,
    "building": {
        "id": 1,
        "address": "г. Москва, ул. Ленина 1",
        "latitude": 55.7558,
        "longitude": 37.6173
    },
    "phonenumbers": [
        {"id": 1, "phone_number": "2-222-222"},
        {"id": 2, "phone_number": "3-333-333"}
    ],
    "activities": [
        {"id": 1, "name": "Молочная продукция"},
        {"id": 2, "name": "Мясная продукция"}
    ]
}

Здание (Building)

{
    "id": 1,
    "address": "г. Москва, ул. Ленина 1, офис 3",
    "latitude": 55.7558,
    "longitude": 37.6173,
    "organizations": [
        {
            "id": 1,
            "legal_name": "ООО Рога и Копыта"
        }
    ]
}

Деятельность (Activity) - древовидная структура

{
    "id": 1,
    "name": "Еда",
    "parent_id": null,
    "level": 0,
    "parent": null,
    "children": [
        {
            "id": 2,
            "name": "Мясная продукция",
            "parent_id": 1,
            "level": 1,
            "children": []
        }
    ],
    "organizations": [
        {
            "id": 1,
            "legal_name": "ООО Рога и Копыта"
        }
    ]
}

API маршруты

Основные CRUD операции

Организации

Здания

Виды деятельности

Расширенный поиск организаций

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

Поиск по названию:

curl -H "X-API-Key: secret-static-api-key" \
  "http://localhost:8000/api/v1/organizations/search/name?name=Рога"

Геопоиск в радиусе:

curl -H "X-API-Key: secret-static-api-key" \
  "http://localhost:8000/api/v1/organizations/search/radius?lat=55.7558&lon=37.6173&radius_km=5"

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

Все запросы требуют заголовок API-ключа:

X-API-Key: secret-static-api-key

Разработка

Локальная установка для разработки

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

   pip install uv
   uv sync

2. Настройка окружения
   Создайте или отредактируйте конфигурационный файл orghandbookapi.toml:

   [run]
   host = "127.0.0.1"
   port = 8000
   
   [database]
   host = "localhost"
   port = 5432
   name = "orghandbookapi"
   user = "admin"
   password = "password"
   
   [security]
   api_key = "your-development-api-key"
   api_key_header = "X-API-Key"
   

3. Запуск миграций базы данных

   alembic upgrade head

4. Запуск сервера для разработки

   uvicorn orghandbookapi.app:app --reload --host 0.0.0.0 --port 8000

Запуск тестов

# Все тесты
pytest tests/ -v

# С покрытием кода
pytest --cov=orghandbookapi tests/

# С параллельным выполнением
pytest -n auto tests/

Code Quality

# Линтинг
ruff check .

# Форматирование
ruff format .

Технологический стек

📄 Лицензия и поддержка

Данный проект лицензирован под GNU GPL 3 - просмотрите файл LICENSE для деталей.

Для коммерческого использования или вопросов по сотрудничеству напишите на alexeev.dev@mail.ru.

Документация |
Сообщить об ошибке |
Предложить улучшение

REST API справочника организаций
Copyright © 2025 Alexeev Bronislav. Все права защищены.