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…

Installation

Install from PyPI using pip:

pip install core-apis
uv pip install core-apis  # Or using UV...

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

How to use it

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

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

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

# -*- 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 built. 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 after the application has already been created. Useful for dynamic or conditional route registration.

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

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

Using @wrap_response — standardized response contract (ApiResponse):

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

from core_https import HTTPStatus
from core_apis.decorators import wrap_response

@wrap_response
def get_item(item_id: int):
    return HTTPStatus.OK, {"id": item_id, "name": "Widget"}

# Returns an ApiResponse dict:
# {"code": 200, "status": "success", "result": {"id": 1, "name": "Widget"}, "error": None}

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

Quick Start

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

pip install --upgrade pip
pip install virtualenv

virtualenv --python=python3.12 .venv

source .venv/bin/activate

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

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.

Links

• Documentation: https://core-apis.readthedocs.io/en/latest/

• Repository: https://gitlab.com/bytecode-solutions/core/core-apis

• Issues: https://gitlab.com/bytecode-solutions/core/core-apis/-/issues

• Changelog: https://gitlab.com/bytecode-solutions/core/core-apis/-/blob/master/CHANGELOG.md

• PyPI: https://pypi.org/project/core-apis/

Support

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

Authors

• Alejandro Cora González - Initial work - alek.cora.glez@gmail.com