API Exposure Guide

The GraphQL Interface

Interacting with the Rescile controller via GraphQL for querying, traversal, real-time subscriptions, and global queries.

Edit this page on GitHub

The GraphQL Interface

The primary way to extract information from Rescile is through its dynamically generated GraphQL API at /graphql. The built-in GraphiQL explorer (at /graphiql) provides auto-complete and schema documentation based on the resource types in your graph. For the complete GraphQL schema reference, see the GraphQL Schema Reference.

Querying and Traversal

Every resource type (e.g., server, application, database) is automatically exposed as a top-level query field. You can filter by any property and traverse relationships (edges) deeply in a single request.

When traversing relationships, the response is split to provide both edge metadata and the target node’s properties:

  • node: The properties of the connected target resource.
  • properties: The properties of the relationship (edge), including the relation type and any compliance controls.
query BlastRadiusAnalysis {
  database(filter: { name: "billing-db-prod" }) {
    name
    environment
    # Traverse relationships backward to find dependent applications
    application {
      properties {
        relation
      }
      node {
        name
        owner
      }
    }
  }
}

Real-Time Subscriptions (WebSockets)

To allow clients to react to architecture changes in real-time without polling, Rescile provides a WebSocket endpoint at /graphql/ws implementing the standard graphql-ws protocol.

Currently, it exposes a coarse-grained global event:

  • graphUpdated: A subscription that yields a timestamp string whenever the importer completes a successful rebuild or an automated mutation successfully alters the graph.
subscription OnGraphUpdated {
  graphUpdated
}

Clients can use this “tick” to instantly re-fetch the specific queries they care about without polling.

Global & Utility Queries

Beyond standard resource queries, Rescile provides several top-level queries to inspect the graph structure and perform pathfinding:

  • Graph Statistics:
    • countNodes: Total number of nodes (vertices).
    • countEdges: Total number of relationships (edges).
    • countResourceTypes: Total number of unique node labels.
    • countRelationTypes: Total number of unique edge labels.
    • countNodeProperties / countEdgeProperties: Total properties across the graph.
  • Introspection:
    • listNodes(label: "server"): Returns all node types and their primary keys.
  • Pathfinding:
    • findPaths(startLabel: "server", startName: "web-01", endLabel: "database"): Executes a breadth-first search to find all unique paths between a specific starting resource and any resource of a target type.
  • Raw Export:
    • graphJson: Returns the entire underlying graph as a raw JSON string.