API#

How to Use#

For an example of the structure of a production-ready project check: bytecode-solutions/examples/fastapi-project

Create the virtual environment…

virtualenv .venv
source .venv/bin/activate
pip install core-apis

The simple way to spin up the FastAPI server and running it locally using uvicorn…

# -*- coding: utf-8 -*-
from core_apis.api import server
server.run()

Creating an application with custom configuration (AppConfig / CorsConfig)…

Pass an AppConfig instance to create_application() to customise the application name, version, CORS, debug mode, and base path. CorsConfig controls the CORS middleware; set enabled=True and supply the allowed origins, methods, and headers.

# -*- coding: utf-8 -*-
from core_apis.api import create_application, AppConfig, CorsConfig

app = create_application(
    app_config=AppConfig(
        name="My Service",
        version="1.0.0",
        cors_config=CorsConfig(
            enabled=True,
            origins=["https://example.com"],
        ),
    ),
)

Adding custom routers —> plugin architecture (recommended)…

Use add_router() to register routers at import time. They are collected by create_application() when the app is created. This is the recommended pattern for plugins and reusable components that don’t need a reference to the app instance.

# -*- coding: utf-8 -*-

from fastapi import APIRouter

from core_apis.api import server
from core_apis.api.routers import add_router

router = APIRouter()
add_router(router)

@router.get(path="/server_status")
def get_server_status():
    return {"status": "OK"}

server.run()

Adding routers at runtime (post-creation)…

Use app.include_router() directly on the FastAPI instance to attach a router after the application has already been created. This is useful for dynamic or conditional route registration during execution.

# -*- coding: utf-8 -*-

from fastapi import APIRouter

from core_apis.api import create_application

app = create_application()

late_router = APIRouter()

@late_router.get(path="/status")
def get_status():
    return {"status": "OK"}

# Attach immediately to the running app instance
app.include_router(late_router, prefix="/api")

FastAPI application factory and configuration.

This module provides the main application factory function for creating configured FastAPI instances with routing, middleware, and health checks.

class core_apis.api.AppConfig(name: str = 'API Service', description: str = 'API Service example...', version: str = '0.0.1', base_path: str = '/api', cors_config: CorsConfig | None = None, debug: bool = False)[source]#

Bases: object

Configuration for the FastAPI application.

Parameters:

  • name – Application name.

  • description – API description.

  • version – The version.

  • base_path – The base path to use when the routes are registered.

  • cors_config – CORS configuration. Pass a CorsConfig instance to enable and configure the CORS middleware.

  • debug – True for debugging.

name: str = 'API Service'#
description: str = 'API Service example...'#
version: str = '0.0.1'#
base_path: str = '/api'#
cors_config: CorsConfig | None = None#
debug: bool = False#
__init__(name: str = 'API Service', description: str = 'API Service example...', version: str = '0.0.1', base_path: str = '/api', cors_config: CorsConfig | None = None, debug: bool = False) → None#
core_apis.api.create_application(app_config: AppConfig | None = None, **kwargs) → FastAPI[source]#

It creates the FastAPI application. Remember to inject the routers before creating the application like:

from fastapi import APIRouter

from core_apis.api import server
from core_apis.api.routers import add_router

router = APIRouter()
add_router(router)

@router.get(path="/server_status")
def new_router():
    return {"status": "OK"}

server.run()
Parameters:

  • app_config – Application configuration. Pass an AppConfig instance to customize name, version, CORS, debug mode, and more. Defaults to AppConfig with all default values.

  • kwargs – Additional keyword arguments passed directly to FastAPI.

Returns:

Returns the FastAPI application.

class core_apis.api.CorsConfig(enabled: bool = False, origins: list[str] = <factory>, methods: list[str] = <factory>, headers: list[str] = <factory>)[source]#

Bases: object

Configuration for the CORS middleware.

Parameters:

  • enabled – Whether to enable CORS middleware.

  • origins – Allowed origins. Defaults to ["*"].

  • methods – Allowed HTTP methods. Defaults to ["*"].

  • headers – Allowed headers. Defaults to ["*"].

enabled: bool = False#
origins: list[str]#
methods: list[str]#
headers: list[str]#
__init__(enabled: bool = False, origins: list[str] = <factory>, methods: list[str] = <factory>, headers: list[str] = <factory>) → None#

Application configuration dataclass.

This module provides the AppConfig dataclass used to configure the FastAPI application in create_application().

class core_apis.api.config.AppConfig(name: str = 'API Service', description: str = 'API Service example...', version: str = '0.0.1', base_path: str = '/api', cors_config: CorsConfig | None = None, debug: bool = False)[source]#

Bases: object

Configuration for the FastAPI application.

Parameters:

  • name – Application name.

  • description – API description.

  • version – The version.

  • base_path – The base path to use when the routes are registered.

  • cors_config – CORS configuration. Pass a CorsConfig instance to enable and configure the CORS middleware.

  • debug – True for debugging.

name: str = 'API Service'#
description: str = 'API Service example...'#
version: str = '0.0.1'#
base_path: str = '/api'#
cors_config: CorsConfig | None = None#
debug: bool = False#
__init__(name: str = 'API Service', description: str = 'API Service example...', version: str = '0.0.1', base_path: str = '/api', cors_config: CorsConfig | None = None, debug: bool = False) → None#

CORS configuration dataclass.

This module provides the CorsConfig dataclass used to configure the CORS middleware in create_application().

class core_apis.api.cors.CorsConfig(enabled: bool = False, origins: list[str] = <factory>, methods: list[str] = <factory>, headers: list[str] = <factory>)[source]#

Bases: object

Configuration for the CORS middleware.

Parameters:

  • enabled – Whether to enable CORS middleware.

  • origins – Allowed origins. Defaults to ["*"].

  • methods – Allowed HTTP methods. Defaults to ["*"].

  • headers – Allowed headers. Defaults to ["*"].

enabled: bool = False#
origins: list[str]#
methods: list[str]#
headers: list[str]#
__init__(enabled: bool = False, origins: list[str] = <factory>, methods: list[str] = <factory>, headers: list[str] = <factory>) → None#

API server module for running FastAPI applications.

This module provides functionality to start and run a FastAPI application using uvicorn as the ASGI server. Configuration is controlled through environment variables for flexibility in different deployment environments.

core_apis.api.server.run(app: FastAPI | None = None) → None[source]#

Start the API server using uvicorn.

Launches a FastAPI application with uvicorn ASGI server. If no application is provided, a default application will be created with CORS middleware enabled.

Parameters:

app – Optional FastAPI application instance. If None, a default application will be created using environment configuration.

Environment Variables:

API_NAME: Name of the API service (default: “API-Service”) DEBUG: Enable debug mode, set to “1” to enable (default: disabled) HOST: Server host address (default: “127.0.0.1” for security) PORT: Server port number (default: 3500) LOG_LEVEL: Uvicorn log level (default: “info”)

Note

The default host is “127.0.0.1” (localhost only) for security. To expose the server to all interfaces, set HOST=”0.0.0.0”.

Router management for FastAPI applications.

This module provides a registry for dynamically adding routers to the FastAPI application before it’s created.

core_apis.api.routers.add_router(router: APIRouter) → None[source]#

Register a router to be included in the FastAPI application.

Routers must be added before calling create_application() to be included in the final application instance.

Parameters:

router – The APIRouter instance to register.

core_apis.api.routers.reset_routers() → None[source]#

Clear all registered routers from the registry. Useful in tests to prevent router state from leaking between test cases.

Health check router for API monitoring.

This module provides a simple health check endpoint that can be used for monitoring, load balancer health checks, and service discovery.

core_apis.api.routers.health.health()[source]#

It’s the default endpoint is injected to the API… [GET] /api/ping -> return “PONG”