create_app¶

add_major_version_base_url(app, index=False) ¶

Add mandatory vMajor endpoints, i.e. all except /versions.

Source code in optimade/server/create_app.py

def add_major_version_base_url(app: FastAPI, index: bool = False):
    """Add mandatory vMajor endpoints, i.e. all except /versions."""
    for endpoint in INDEX_ENDPOINTS if index else MAIN_ENDPOINTS:
        app.include_router(
            endpoint.router, prefix=BASE_URL_PREFIXES["major"], include_in_schema=False
        )

add_optional_versioned_base_urls(app, index=False) ¶

Add the following OPTIONAL prefixes/base URLs to server:

    /vMajor.Minor
    /vMajor.Minor.Patch

Source code in optimade/server/create_app.py

def add_optional_versioned_base_urls(app: FastAPI, index: bool = False):
    """Add the following OPTIONAL prefixes/base URLs to server:
    ```
        /vMajor.Minor
        /vMajor.Minor.Patch
    ```
    """
    for version in ("minor", "patch"):
        for endpoint in INDEX_ENDPOINTS if index else MAIN_ENDPOINTS:
            app.include_router(
                endpoint.router,
                prefix=BASE_URL_PREFIXES[version],
                include_in_schema=False,
            )

create_app(config=None, index=False, logger_tag=None) ¶

Create and configure a FastAPI app for the OPTIMADE API.

Sets up logging, middleware, exception handlers, routers, and optional test/JSONL data insertion. Can be used for both a regular OPTIMADE API or the index meta-database variant.

Note that the global ServerConfig instance is read from the "OPTIMADE_" env variables or the config json file, but this function allows to override config options for individual apps by passing a custom ServerConfig.

Parameters:

Name Type Description Default

config	ServerConfig \| None	ServerConfig instance to override config options specific to this app.	None
index	bool	If True, create an index meta-database instance.	False
logger_tag	str \| None	Optional tag for the logger.	None

Returns:

Type Description

FastAPI

Configured FastAPI application.

Source code in optimade/server/create_app.py

def create_app(
    config: ServerConfig | None = None,
    index: bool = False,
    logger_tag: str | None = None,
) -> FastAPI:
    """
    Create and configure a FastAPI app for the OPTIMADE API.

    Sets up logging, middleware, exception handlers, routers, and optional
    test/JSONL data insertion. Can be used for both a regular OPTIMADE API
    or the index meta-database variant.

    Note that the global ServerConfig instance is read from the "OPTIMADE_"
    env variables or the config json file, but this function allows to
    override config options for individual apps by passing a custom ServerConfig.

    Args:
        config: ServerConfig instance to override config options specific to this app.
        index: If True, create an index meta-database instance.
        logger_tag: Optional tag for the logger.

    Returns:
        Configured FastAPI application.
    """

    # create app-specific logger
    logger = create_logger(logger_tag, config)

    if config_warnings:
        logger.warning(
            f"Invalid config file or no config file provided, running server with default settings. Errors: "
            f"{[warnings.formatwarning(w.message, w.category, w.filename, w.lineno, '') for w in config_warnings]}"
        )
    else:
        logger.info(
            f"Loaded settings from {os.getenv('OPTIMADE_CONFIG_FILE', DEFAULT_CONFIG_FILE_PATH)}"
        )

    if config is None:
        config = ServerConfig()

    if config.debug:  # pragma: no cover
        logger.info("DEBUG MODE")

    title = "OPTIMADE API" if not index else "OPTIMADE API - Index meta-database"
    description = """The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n"""
    if index:
        description += 'This is the "special" index meta-database.\n'
    description += f"\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v{__version__}) v{__version__}."

    if index:
        config.is_index = True

    app = FastAPI(
        root_path=config.root_path,
        title=title,
        description=description,
        version=__api_version__,
        docs_url=f"{BASE_URL_PREFIXES['major']}/extensions/docs",
        redoc_url=f"{BASE_URL_PREFIXES['major']}/extensions/redoc",
        openapi_url=f"{BASE_URL_PREFIXES['major']}/extensions/openapi.json",
        default_response_class=JSONAPIResponse,
        separate_input_output_schemas=False,
    )

    # Save the config in the app state for access in endpoints
    app.state.config = config

    # create entry collections and save in app state for access in endpoints
    entry_collections = create_entry_collections(config)
    app.state.entry_collections = entry_collections

    # store also the BaseResourceMapper
    app.state.base_resource_mapper = BaseResourceMapper()

    if not index:
        if config.insert_test_data or config.insert_from_jsonl:
            insert_main_data(config, entry_collections, logger)
    else:
        if config.insert_test_data and config.index_links_path.exists():
            insert_index_data(config, entry_collections, logger)

    # Add middleware to set logging context
    @app.middleware("http")
    async def set_context(request, call_next):
        set_logging_context(logger_tag)
        response = await call_next(request)
        return response

    # Add CORS middleware
    app.add_middleware(CORSMiddleware, allow_origins=["*"])

    # Then add required OPTIMADE middleware
    for middleware in OPTIMADE_MIDDLEWARE:
        app.add_middleware(middleware)

    # Enable GZIP after other middleware.
    if config.gzip.enabled:
        app.add_middleware(
            GZipMiddleware,
            minimum_size=config.gzip.minimum_size,
            compresslevel=config.gzip.compresslevel,
        )

    # Add exception handlers
    for exception, handler in OPTIMADE_EXCEPTIONS:
        app.add_exception_handler(exception, handler)

    # Add various endpoints to unversioned URL
    endpoints = INDEX_ENDPOINTS if index else MAIN_ENDPOINTS
    endpoints += [versions]
    for endpoint in endpoints:
        app.include_router(endpoint.router)

    # add the versioned endpoints
    add_major_version_base_url(app, index=index)
    add_optional_versioned_base_urls(app, index=index)

    return app