.. module:: API


API
=========================

How to Use
-----------------------------------------------------------------------------------

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

Create the virtual environment...

.. code-block:: shell

    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`...

.. code-block:: python

    # -*- 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.

.. code-block:: python

    # -*- 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.

.. code-block:: python

    # -*- 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.

.. code-block:: python

    # -*- 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")
..

.. automodule:: core_apis.api
   :members:
   :undoc-members:
   :show-inheritance:
   :private-members:

.. automodule:: core_apis.api.config
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: core_apis.api.cors
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: core_apis.api.server
   :members:
   :undoc-members:
   :show-inheritance:
   :private-members:

.. automodule:: core_apis.api.routers
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: core_apis.api.routers.health
   :members:
   :undoc-members:
   :show-inheritance:
   :private-members: