GraphQL

Clients specify the precise shape and fields of the response in the query itself, eliminating over-fetching and under-fetching. The server returns only what is requested, no more and no less. This shifts control from the server to the client, enabling frontend teams to iterate faster without backend changes.

• Field Selection: Request only patient.name and patient.mrn instead of the entire patient object
• Nested Resources: Traverse relationships like patient.encounters.diagnosis in a single round trip
• Aliases: Rename fields in the response to avoid naming conflicts when querying the same field with different arguments

Every GraphQL API is defined by a strict type system using the Schema Definition Language (SDL). The schema acts as a contract between client and server, specifying object types, fields, relationships, and enumerations. This enables introspection, where tools can automatically query the schema to generate documentation, autocomplete, and validation.

• Scalar Types: Built-in primitives like String, Int, Float, Boolean, and ID
• Object Types: Custom types like Patient with fields that resolve to scalars or other objects
• Enumeration Types: Restrict fields to a predefined set of values, such as Gender: MALE | FEMALE | OTHER
• Non-Null Modifier: Enforce required fields with String! to guarantee data integrity

Unlike REST APIs that require multiple endpoints for different resources, a GraphQL API exposes a single /graphql endpoint. All queries, mutations, and subscriptions are sent to this one URL via HTTP POST. This simplifies client configuration, reduces network overhead, and centralizes authentication, logging, and rate limiting.

• Query Operation: Read-only data retrieval, analogous to HTTP GET
• Mutation Operation: Write operations that modify server-side data, analogous to POST/PUT/DELETE
• Subscription Operation: Real-time event streams over WebSockets for live data updates
• Batching: Multiple queries can be sent in a single HTTP request as an array

Each field in a GraphQL schema is backed by a resolver—a function that knows how to fetch the data for that field. Resolvers compose a directed acyclic graph of execution, where parent resolvers pass their resolved values to child resolvers. This enables fetching data from multiple sources like databases, REST APIs, and gRPC services in a single query.

• Root Resolvers: Entry points for Query, Mutation, and Subscription types
• Field-Level Resolvers: Granular functions that resolve individual fields, enabling lazy loading
• DataLoader Pattern: Batching and caching utility to avoid the N+1 query problem when fetching related entities
• Context Object: Shared mutable object passed through the resolver chain for authentication tokens and database connections

GraphQL servers expose a built-in introspection query that allows tools to discover the schema's types, fields, directives, and documentation at runtime. This powers developer tools like GraphiQL and Apollo Studio, which provide interactive API explorers with autocomplete, real-time validation, and schema visualization without requiring external documentation.

• __schema Query: Returns the full type system including types, queries, mutations, and subscriptions
• __type Query: Retrieves detailed information about a specific type, including its fields and arguments
• Deprecation Tracking: Fields can be marked with @deprecated and a reason, surfaced in tooling
• Schema Stitching: Introspection enables federated gateways to compose multiple subgraphs into a unified supergraph

Fragments are reusable units of field selection that reduce duplication in queries. They allow developers to define a set of fields once and spread them into multiple queries, mutations, or other fragments. This is essential for component-based UI frameworks like React, where each component can declare its own data dependencies.

• Named Fragments: fragment PatientInfo on Patient { name mrn dob } can be reused across queries
• Inline Fragments: Conditional field selection based on the concrete type in a union or interface
• Fragment Matching: Tools like Relay enforce colocation of fragments with components for optimal data fetching
• Type Conditions: Use ... on TypeName to access fields specific to a particular implementation of an interface