GraphQL API

Query InfraKitchen's domain entities through the GraphQL API.

InfraKitchen exposes a GraphQL API alongside the REST API, powered by Strawberry GraphQL. It provides a flexible way to query all domain entities with field-level optimization — you only fetch the data you need.

Endpoint

The GraphQL API is available at /api/graphql. This endpoint serves both the GraphiQL interactive UI (when opened in a browser) and standard GraphQL POST requests.

Authentication

All queries require a valid Bearer token in the Authorization header. The same JWT tokens used for the REST API work with GraphQL.

Authorization: Bearer <your-token>

Without a token, queries return a GraphQL error:

{
  "data": null,
  "errors": [
    {
      "message": "Not authenticated. Please provide a valid bearer token in the Authorization header."
    }
  ]
}

Using the GraphiQL UI

The built-in GraphiQL UI is accessible at /api/graphql in the browser. To authenticate:

1. Open /api/graphql in your browser

2. Click the Headers tab at the bottom of the editor panel

3. Add your authorization header:

   {
     "Authorization": "Bearer <your-token>"
   }

4. Write and run queries — the UI provides autocompletion and schema documentation

Query Examples

Fetch a single resource

query {
  resource(id: "550e8400-e29b-41d4-a716-446655440000") {
    id
    name
    state
    status
    template {
      name
    }
    creator {
      name
    }
  }
}

List templates with filtering, sorting, and pagination

All list queries support optional filter, sort, and range parameters:

query {
  templates(
    filter: { name: "my-template" }
    sort: ["name", "ASC"]
    range: [0, 10]
  ) {
    id
    name
    description
    executors {
      name
      runtime
    }
  }
}

Fetch executors with related entities

query {
  executors {
    id
    name
    runtime
    sourceCode {
      sourceCodeUrl
      identifier
    }
    storage {
      name
    }
    integrationIds {
      name
      integrationProvider
    }
  }
}

Filtering, Sorting & Pagination

List queries accept three optional arguments:

These use the same filtering, sorting, and pagination logic as the REST API.

Field-Level Optimization

The GraphQL API includes automatic field-level query optimization:

• SQL column selection — Only the database columns corresponding to requested GraphQL fields are loaded (load_only)
• Relationship loading — Related entities (e.g., template, creator, sourceCode) are eagerly loaded only when requested in the query
• No N+1 queries — Relationships use selectinload to batch-load in a single query

This means a simple query like { templates { id name } } will only SELECT id, name FROM templates — no unnecessary data is fetched.

Usage Examples

cURL

curl -X POST https://<your-infrakitchen-host>/api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"query": "{ templates { id name } }"}'