GraphQL API

Overview

The xclade GraphQL API is a specialized, high-performance layer built directly on top of the Medusa v2 Query Engine. Unlike traditional "black box" API wrappers, it is designed as a thin, efficient compatibility layer using GraphQL Yoga.

Architecture

The system follows a zero-overhead architecture designed to solve specific e-commerce performance challenges:

graph TD
    Client[Client Request] --> Yoga[GraphQL Yoga Endpoint]
    Yoga --> DataLoader[DataLoader Batching]
    DataLoader --> Engine[Medusa Query Engine]
    Engine --> DB[(PostgreSQL)]

Key Capabilities

• Zero Over-fetching: Clients request exactly the fields they need. A query for { id title } returns a ~2KB payload compared to ~500KB for a full REST response.
• N+1 Prevention: Integrated DataLoader primitives automatically batch database queries within a 10ms window, reducing 100+ database calls to a single optimized query.
• Production Ready: Built on the same authentication and permission primitives as the core REST API, ensuring consistent security rules.

Availability

The GraphQL API is currently available for:

• Products: Full coverage of catalog, variants, options, and metadata.
• Collections: Hierarchical product grouping.

Additional entities (Orders, Customers, Carts) are under active development.

Endpoint

All queries and mutations are served from a single endpoint:

POST https://{your-tenant}.api.myxclade.com/graphql