GraphQL API

Relevant source files

The following files were used as context for generating this wiki page:

• src/graphql/query_root.rs
• src/controllers/graphql.rs
• src/initializers/graphql.rs
• examples/axum_example/api/src/lib.rs
• src/app.rs
• sea-orm-pro/src/config.rs

The GraphQL API in SeaORM Pro provides a dynamic interface for interacting with the underlying database schema. Built using async-graphql and seaography, it automatically maps SeaORM entities to GraphQL objects, enabling complex queries and mutations with minimal manual configuration. The system is designed to integrate seamlessly with the Axum web framework and the Loco.rs ecosystem.

The API serves two primary purposes: facilitating the data requirements of the professional admin panel and providing a developer-friendly GraphQL Playground for schema exploration and manual testing. It includes built-in support for query complexity limits, depth limits, and security via JWT authentication.

System Architecture

The GraphQL implementation follows a modular architecture where the schema is constructed dynamically from registered SeaORM entities and served via dedicated Axum routes.

Component Overview

Component	Responsibility
GraphQLInitializer	Responsible for building the schema during application startup and inserting it into the shared store.
QueryRoot	Defines the schema construction logic, including limits and extensions like Readonly mode.
GraphQL Handler	An Axum controller that processes incoming POST requests and executes them against the schema.
Playground	A GET endpoint that serves the async-graphql interactive playground interface.

Sources: src/initializers/graphql.rs:11-25, src/controllers/graphql.rs:43-52, src/graphql/query_root.rs:26-44

Request Flow

The following diagram illustrates the lifecycle of a GraphQL request, from the initial client call to database execution.

The system ensures that the user's identity is propagated through the UserContext to allow for row-level security or auditing within the GraphQL resolvers.
Sources: src/controllers/graphql.rs:22-41, examples/axum_example/api/src/lib.rs:271-285

Schema Construction and Configuration

The schema is generated by the Builder from seaography, which uses a BuilderContext to manage lifecycle hooks and entity mapping.

Query Limits and Safety

To prevent Denial of Service (DoS) attacks through overly complex queries, the system enforces limits on query structure.

Limit Type	Default Value	Description
DEPTH	100	The maximum number of nested levels allowed in a single GraphQL query.
COMPLEXITY	1000	The maximum calculated complexity score for a query.

Sources: src/initializers/graphql.rs:7-10, src/graphql/query_root.rs:35-38

Readonly Mode

For demo environments, the system implements a Readonly extension. This extension intercepts the query parsing phase and blocks any operation identified as a Mutation.

API Endpoints

The GraphQL API is typically prefixed under /api/graphql (or /graphql depending on application configuration).

Handler Implementation

The handler performs the following steps:

1. Validates the JWT token from the Authorization header.
2. Retrieves the user from the database to establish a session.
3. Attaches seaography::UserContext to the request data.
4. Executes the request against the schema stored in the AppContext.

Sources: src/controllers/graphql.rs:22-41, src/app.rs:59-66

Playground Configuration

The Playground is configured to automatically include authentication tokens from the browser's local storage, ensuring that developers can test protected queries without manually updating headers.

async fn graphql_playground() -> Result<Response> {
    let config = GraphQLPlaygroundConfig::new("/api/graphql")
        .with_header("Authorization", "AUTO_TOKEN");

    let res = playground_source(config).replace(
        r#""Authorization":"AUTO_TOKEN""#,
        r#""Authorization":`Bearer ${localStorage.getItem('auth_token')}`"#,
    );

    Ok(Response::new(res.into()))
}

Sources: src/controllers/graphql.rs:9-20, examples/axum_example/api/src/lib.rs:260-269

Integration with Admin Panel

The professional admin panel relies on the GraphQL API for its "Raw Tables" and "Composite Tables" views. The sea-orm-pro library provides configuration structures to toggle the visibility of the GraphQL Playground within the admin navbar.

• Config Path: site.navbar.graphql_playground (boolean)
• Source File: sea-orm-pro/src/config.rs

Sources: sea-orm-pro/src/config.rs:54-57, pro_admin/config.toml:11-12

Conclusion

The GraphQL API module provides a robust, auto-generated interface for SeaORM entities. By leveraging seaography and async-graphql, it reduces the boilerplate required to build data-rich applications while maintaining strict control over query complexity and security through its integration with the project's authentication system and initializer patterns.