GraphQL API Integration
Relevant source files
The following files were used as context for generating this wiki page:
GraphQL API Integration provides the primary interface for programmatically interacting with the Infrahub server. The SDK abstracts the underlying GraphQL API so developers work with infrastructure data as native Python objects. It manages authentication, batching, caching, and data tracking through its client implementations.
The system utilizes graphql-core for query parsing and httpx for transport. It supports both InfrahubClient for asynchronous operations and InfrahubClientSync for synchronous operations, ensuring dual API parity across all public features.
Sources: AGENTS.md:3-8, dev/constitution.md:21-25
Architecture and Query Rendering
The GraphQL integration centers around a rendering engine that prepares queries for execution by the Infrahub server. This engine processes query strings and manages the inclusion of reusable components known as fragments.
Query Renderer Logic
The query_renderer.py module handles the transformation of raw GraphQL strings into fully formed queries. The rendering process involves building a fragment index and resolving dependencies between different GraphQL files.
build_fragment_index: Analyzes fragment files to create a mapping of fragment names to their definition nodes.collect_required_fragments: Scans a GraphQL document to identify all required fragments, including transitive dependencies.render_query_with_fragments: Inlines the definitions of required fragments into the final query string sent to the server.render_query: Acts as the high-level entry point used by the CLI to load queries and fragments from the repository configuration.
Sources: specs/infp-496-graphql-fragment-inlining/tasks.md:58-68
Fragment Inlining Flow
The SDK resolves transitive fragment dependencies to allow modular query design. If a query references a fragment that in turn references another fragment, the renderer ensures all necessary definitions are included in the output.
This diagram shows the logic flow for preparing a GraphQL query with fragment support.
Sources: specs/infp-496-graphql-fragment-inlining/tasks.md:62-65, specs/infp-496-graphql-fragment-inlining/tasks.md:105-112
Data Management and Operations
The SDK provides several mechanisms for interacting with the GraphQL API to perform CRUD (Create, Read, Update, Delete) operations.
Interaction Workflow
The infrahubctl CLI and external applications interact with the Infrahub server through the SDK's client layer. The following diagram illustrates a typical query execution sequence:
This diagram shows the sequence of calls from the CLI through the SDK to the remote server.
Sources: specs/infp-496-graphql-fragment-inlining/tasks.md:135-145, AGENTS.md:46-51
Key Features of GraphQL Integration
| Feature | Description |
|---|---|
| Dual Client | Supports both InfrahubClient (async) and InfrahubClientSync (sync). |
| Fragment Inlining | Automatically resolves and includes required fragments from multiple files. |
| Pagination | Supports large result sets via --limit and --offset parameters. |
| Filtering | Enables complex server-side filtering using attribute and relationship values. |
| Batching | Processes multiple object creations or updates from a single file input. |
Sources: dev/constitution.md:21-30, specs/001-end-user-cli/spec.md:200-220
Configuration and Schema Discovery
GraphQL resources are declared within the repository configuration, typically in a .infrahub.yml file.
Repository Configuration
The SDK parses the graphql_fragments and graphql_queries sections of the configuration to locate GraphQL assets on disk.
graphql_fragments: A list ofInfrahubRepositoryFragmentConfigobjects containing names and file paths to.gqlfiles.graphql_queries: Configurations for GraphQL queries that the SDK can load and render by name.
Sources: specs/infp-496-graphql-fragment-inlining/tasks.md:52-57
Schema Discovery Commands
Users explore the available GraphQL schema through dedicated CLI commands:
infrahubctl schema list: Retrieves all available kinds with their namespaces and descriptions.infrahubctl schema show <kind>: Displays the attributes, relationships, and constraints for a specific kind.
Sources: specs/001-end-user-cli/tasks.md:144-155
Error Handling
Precise error handling is implemented through a typed exception hierarchy rooted at GraphQLQueryError. This allows consumers to handle specific failure modes programmatically.
GraphQL Exception Types
| Exception | Condition for Raising |
|---|---|
QuerySyntaxError | Invalid GraphQL syntax in a query or fragment file. |
FragmentNotFoundError | A fragment spread references a name absent from all fragment files. |
DuplicateFragmentError | The same fragment name appears in multiple files or content strings. |
CircularFragmentError | A circular dependency cycle is detected (e.g., Fragment A -> B -> A). |
FragmentFileNotFoundError | The specified path for a fragment file does not exist. |
Sources: specs/infp-496-graphql-fragment-inlining/tasks.md:44-50, specs/infp-496-graphql-fragment-inlining/tasks.md:120-128
The GraphQL API Integration ensures that all infrastructure data interactions remain consistent, typed, and efficient, whether performed through the CLI or custom Python applications. End-to-end integration tests verify that queries, fragment inlining, and data operations function correctly against a live Infrahub server.