core-apis#

This project/library contains useful elements related to APIs and provides basic structures to speed up the implementation of an API service using the FastApi framework as base…

Python Versions License Pipeline Status Docs Status Security

Documentation Contents#

Contents:

Features#

FastAPI Server Management

  • Quick server setup with uvicorn ASGI server

  • Environment-based configuration (HOST, PORT, DEBUG, LOG_LEVEL)

  • Secure defaults (localhost-only binding)

Application Factory

  • AppConfig dataclass consolidating all application parameters (name, version, description, base_path, cors_config, debug)

  • CorsConfig dataclass for CORS middleware (origins, methods, headers)

  • create_application(app_config: AppConfig) factory with safe defaults

Router Management

  • Plugin architecture: register routers at import time via add_router()

  • Runtime addition: attach routers to an existing app via app.include_router()

  • reset_routers() for clearing the registry between tests

  • Built-in health check endpoint (/api/ping)

Response Standardization

  • @wrap_response decorator for consistent API responses

  • ApiResponse TypedDict contract: code, status, result, error

  • HTTP status code mapping (2XX success, 4XX error, 5XX failure)

  • Automatic exception handling for ServiceException and InternalServerError

Testing Utilities

  • BaseApiTestCases class for FastAPI testing with pre-configured TestClient

  • setUp() calls reset_routers() automatically to prevent cross-test pollution

  • init_client(with_cors=True) for flexible test application initialization

Installation#

Install the package:

pip install core-apis
uv pip install core-apis    # Or using UV...
pip install -e ".[dev]"     # For development...

How to use it#

The simple way to spin up the FastAPI server locally using uvicorn:

from core_apis.api import server
server.run()

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

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):

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):

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"}

app.include_router(late_router, prefix="/api")

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

Setting Up Environment#

  1. Install required libraries:

pip install --upgrade pip
pip install virtualenv

  1. Create Python virtual environment:

virtualenv --python=python3.12 .venv

  1. Activate the virtual environment:

source .venv/bin/activate

Install packages#

pip install .
pip install -e ".[dev]"

Check tests and coverage#

python manager.py run-tests
python manager.py run-coverage

Contributing#

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Write tests for new functionality

  4. Ensure all tests pass: pytest -n auto

  5. Run linting: pylint core_apis

  6. Run security checks: bandit -r core_apis

  7. Submit a pull request

License#

This project is licensed under the MIT License. See the LICENSE file for details.

Support#

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors#