API Architecture¶

Status: Implemented

Overview¶

The Nivron API is the primary interface between clients and the Control Plane.

Built on FastAPI, it follows a versioned architecture designed to provide long-term compatibility while allowing the platform to evolve without breaking existing integrations.

Public APIs, operational endpoints and internal services are intentionally separated to preserve security, maintainability and independent evolution.

Objectives¶

Objective	Description
Stable Public API	Provide predictable contracts for clients and integrations.
Separation of Concerns	Distinguish public, internal and operational endpoints.
Versioned Evolution	Introduce new API versions without disrupting existing clients.
Modular Routing	Organize endpoints into reusable routing layers.
Shared Services	Delegate common behavior to the Platform Framework.

Current Routing Structure¶

Path	Responsibility
`api/core/`	Core platform routes.
`api/internal/`	Internal operational endpoints.
`api/v1/`	Public versioned API.
`main.py`	Application bootstrap and router registration.

Request Lifecycle¶

flowchart LR
    CLIENT["Client"]
    FASTAPI["FastAPI"]
    ROUTER["Router"]
    MODULE["Business Module"]
    FRAMEWORK["Platform Framework"]
    DB["PostgreSQL"]

    CLIENT --> FASTAPI
    FASTAPI --> ROUTER
    ROUTER --> MODULE
    MODULE --> FRAMEWORK
    FRAMEWORK --> DB

Business modules own application behavior while shared services are provided by the Platform Framework.

Public Endpoints¶

Endpoint	Purpose
`/`	Platform information page.
`/health`	Service health check.
`/ready`	Readiness validation, including database connectivity.
`/api/v1/platform`	Platform metadata and version information.

These endpoints are intended for public consumers and follow versioned API contracts.

Internal Endpoints¶

Internal endpoints support operational activities and platform coordination.

Endpoint	Purpose
`/internal/status`	Internal platform status protected by platform authentication.

Operational endpoints are not part of the public API contract.

API Versioning¶

The current public API is exposed under:

/api/v1/

Future versions will coexist with previous ones, allowing controlled migration without forcing immediate client upgrades.

Breaking changes should be introduced only through a new API version.

Architectural Principles¶

Principle	Application
Stable Contracts	Public APIs remain predictable.
Explicit Versioning	Breaking changes require a new API version.
Thin Routing Layer	Routers delegate business behavior to application modules.
Business Isolation	Domain logic remains outside routing.
Shared Platform Services	Cross-cutting capabilities come from the Platform Framework.