orghandbookapi documentation¶

Содержание:

orghandbookapi package

org-handbook-api¶

REST API справочника организаций

Ссылки: - Документация API - Исходный код - Лицензия

https://raw.githubusercontent.com/alexeev-prog/org-handbook-api/refs/heads/main/docs/pallet-0.png

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

Основные возможности:

Полный CRUD для организаций, зданий и видов деятельности
Древовидная структура видов деятельности с ограничением вложенности
Геопространственный поиск организаций
Аутентификация через статичный API-ключ
Автоматическая документация Swagger/Redoc

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

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

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

Docker & Docker Compose
Git

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

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

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

Запуск приложения
```
docker-compose up --build -d
```

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

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

Документация API доступна по адресу: http://localhost:8000/docs

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

Организация (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
}

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

{
    "id": 1,
    "name": "Еда",
    "parent_id": null,
    "level": 0,
    "children": [
        {
            "id": 2,
            "name": "Мясная продукция",
            "parent_id": 1,
            "level": 1
        }
    ]
}

API маршруты¶

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

Организации¶

Метод	Endpoint	Описание
GET	/api/v1/organizations/	Список организаций
GET	/api/v1/organizations/{id}	Организация по ID
POST	/api/v1/organizations/	Создание организации
PUT	/api/v1/organizations/{id}	Обновление организации
DELETE	/api/v1/organizations/{id}	Удаление организации

Здания¶

Метод	Endpoint	Описание
GET	/api/v1/buildings/	Список зданий
GET	/api/v1/buildings/{id}	Здание по ID
POST	/api/v1/buildings/	Создание здания
PUT	/api/v1/buildings/{id}	Обновление здания
DELETE	/api/v1/buildings/{id}	Удаление здания

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

Метод	Endpoint	Описание
GET	/api/v1/activity/	Список видов деятельности
GET	/api/v1/activity/{id}	Вид деятельности по ID
POST	/api/v1/activity/	Создание вида деятельности
PUT	/api/v1/activity/{id}	Обновление вида деятельности
DELETE	/api/v1/activity/{id}	Удаление вида деятельности
GET	/api/v1/activity/tree/{parent_id}	Дерево видов деятельности

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

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

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

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

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

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

Разработка¶

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

Установка зависимостей
```
pip install uv
uv sync
```
Настройка окружения

Создайте или отредактируйте конфигурационный файл orghandbookapi.toml
Запуск миграций базы данных
```
alembic upgrade head
```

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

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

Тестирование и качество кода¶

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

pytest tests/ -v

Линтинг и форматирование:

ruff check .
ruff format .

Проверка типов:

mypy orghandbookapi

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

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

— REST API справочника организаций