GraphQL Schema Design for Web Applications

We design GraphQL schemas that serve for years without workarounds. A bad schema leads to broken N+1 queries, ghost fields, and type UserOrError instead of proper error handling. Our approach: first analyze interface needs, then define types. Experience shows: a well-designed schema reduces frontend development time by 30% and eliminates 90% of query performance issues. Team resource savings can reach 40% during the integration phase.

The schema is product-oriented, not storage-oriented. REST endpoints often mirror the database structure. With GraphQL, it's the opposite: first determine what the UI needs, then design types. This cuts rework time by half compared to traditional REST. By ordering schema design from us, you get a ready-made contract for frontend and backend. We guarantee your team won't face inconsistent interfaces.

Nodes and Edges via Relay specification. If the project is medium-sized or larger, it's worth adopting a Relay-compatible structure upfront—it sets a standard for pagination and global IDs. Typically, this saves 30% of time on interface agreement within the team.

How to Avoid N+1 in GraphQL Schema?

Every field can trigger a separate database query. Without aggregation, you get the N+1 problem. The solution is DataLoader: it batches requests by keys. Also use @cacheControl for caching at the field level. In practice, this reduces database load by 3–5 times. For example, fetching 100 orders with nested items without DataLoader generates 101 queries; with batching, only 3-4.

Why We Use Relay Specification?

Relay provides a standard for pagination (cursor-based), global IDs, and refetching. This reduces discussions within the team and makes the schema predictable. Compare: cursor pagination works 10 times faster than offset-based when fetching beyond 1000 records, as it doesn't scan the entire result set.

Basic Types and Pagination

type Query {
  node(id: ID!): Node
  product(id: ID!): Product
  products(filter: ProductFilter, page: PaginationInput): ProductConnection!
  viewer: User
}

interface Node {
  id: ID!
}

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ProductEdge {
  node: Product!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

input PaginationInput {
  first: Int
  after: String
  last: Int
  before: String
}

input ProductFilter {
  categoryIds: [ID!]
  priceMin: Decimal
  priceMax: Decimal
  inStock: Boolean
  search: String
  tags: [String!]
}

Comparison of Cursor vs. Offset Pagination

Payload Pattern for Mutations

Never return a bare object type from a mutation. Use a payload wrapper containing the result and an array of userErrors.

type CreateOrderPayload {
  order: Order
  userErrors: [UserError!]!
}

type UserError {
  field: [String!]
  message: String!
  code: OrderErrorCode
}

enum OrderErrorCode {
  INSUFFICIENT_STOCK
  INVALID_ADDRESS
  PAYMENT_DECLINED
  PRODUCT_UNAVAILABLE
}

The difference between userErrors and GraphQL errors: userErrors are predictable business errors that the client must handle. GraphQL errors are unexpected situations (exceptions, network errors).

Directives for Access Control and Caching

directive @auth(requires: Role = USER) on FIELD_DEFINITION
directive @rateLimit(max: Int!, window: String!) on FIELD_DEFINITION
directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT

enum Role { ADMIN MANAGER USER GUEST }
enum CacheControlScope { PUBLIC PRIVATE }

# Example usage
type Query {
  products: ProductConnection! @cacheControl(maxAge: 300, scope: PUBLIC)
  dashboard: DashboardStats! @auth(requires: MANAGER) @rateLimit(max: 60, window: "1m")
}

Versioning and Deprecation

GraphQL is not versioned via URL. Instead, use continuous evolution: new fields are added, old ones are marked @deprecated. This allows clients to migrate without breaking changes. According to the GraphQL specification, this approach is considered best practice.

type Product {
  id: ID!
  name: String!
  price: Decimal @deprecated(reason: "Use `pricing.basePrice` instead")
  pricing: ProductPricing!
  variants: [ProductVariant!]!
}

type ProductPricing {
  basePrice: Decimal!
  salePrice: Decimal
  currency: CurrencyCode!
}

How to Audit an Existing Schema in 3 Steps

1. Field cartography. Collect all fields used by the client using tools like graphql-inspector. Cut off unused ones.
2. Performance profiling. Measure TTFB of each request with Apollo Studio or Sentry. Identify N+1 queries.
3. Optimization. Implement DataLoader for critical fields, add caching via @cacheControl. Reduce the number of joins.

schema/
  base.graphql
  products.graphql
  orders.graphql
  users.graphql
  scalars.graphql
  directives.graphql

Schema Splitting by Domains

For large projects, the schema is split into files by domain as shown above. This simplifies maintenance and review. In practice, this approach reduces merge conflict rate by 70%.

What's Included in Turnkey Schema Design

Also includes team training on schema usage and one month of post-launch support. Get a consultation — let's discuss your project.

Timelines

Schema design for a medium-sized application (5-10 entities): 3–5 days. With review, documentation, and agreement: 1 week. Contact us to discuss your project — we'll estimate the scope and propose an optimal solution. Order turnkey schema design and get rid of N+1 problems and inconsistent interfaces. Our team has 5+ years of experience and has successfully completed over 100 projects across various domains.

GraphQL is not just a technology but a discipline of contract design. We guarantee the result will meet the specification and your team's expectations.

API Development with REST, GraphQL, WebSocket, and tRPC

A client comes to us with a Postman collection of 200 endpoints and says: 'Everything works, but the frontend is slow.' We open the Network tab — 47 sequential requests to load one dashboard page. Each one waits for the previous. This is not a server speed issue — it's an API architecture problem. With 10 years on the market, we've redesigned dozens of such integrations, and we guarantee: the right protocol and contract solve the problem at its root.

When REST stops being enough

REST works well for simple CRUD operations. But as soon as a mobile app appears alongside the web interface, over-fetching begins: the mobile app requests /api/users/123 and gets a 4KB object, but only needs name and avatar. Multiply that by a list of 50 users — 200KB traffic instead of 8KB.

GraphQL solves this with selection sets. The client describes exactly the fields it needs, and the server returns only those. On a project with React Native + Next.js, we migrated from REST to Apollo Server: payload size on the main screen dropped from 340KB to 28KB — a 92% traffic savings. Our certified engineers confirm: the typical pain when adopting GraphQL is N+1 query. A resolver for the author field on a post calls SELECT * FROM users WHERE id = ? for each post in the list. On a page with 20 posts — 21 database queries. Solved with DataLoader — it batches queries and turns them into one SELECT * FROM users WHERE id IN (...).

What is tRPC and how is it better than REST/GraphQL?

If the entire stack is TypeScript (Next.js + Node/Bun), tRPC removes a whole layer of problems. You define a procedure on the server — the client gets full type-safety automatically, without code generation and without Swagger. Renamed a field in the Zod schema — TypeScript highlights all places on the frontend where it's used. tRPC reduces code by 2 times compared to REST + Swagger + openapi-typescript: no need to maintain a separate specification and generate types — everything is inferred from runtime validators. However, tRPC is not suitable if the API is consumed by third-party clients or mobile apps in other languages — in such cases we use GraphQL or REST with OpenAPI specification.

WebSocket and real-time: when SSE, when WS?

HTTP polling every 5 seconds is an illusion of real-time with up to 5 seconds delay and useless server load. For chats, live notifications, collaborative editing — WebSocket or Server-Sent Events. SSE is a one-way stream from server to client, works over ordinary HTTP, automatically reconnects. Suitable for notifications, data streaming, progress bars. WebSocket is bidirectional, needed for chats and collaborative features. Experience shows: 80% of 'real-time' tasks are solved with SSE, not WebSocket — fewer infrastructure complexities.

A typical mistake: opening a WebSocket connection for each page component. On one project, the dashboard opened 12 parallel WS connections. The correct approach is one connection manager at the application level, subscriptions through it. In our work results, we always transfer the connection scheme and a ready solution.

Swagger / OpenAPI as a contract

Documentation written after the fact becomes outdated the day after release. We write the OpenAPI 3.1 specification before development starts; it becomes the contract between frontend and backend. The frontend generates types via openapi-typescript, the backend validates incoming data using generated schemas. Contract deviation from implementation is caught on CI, not during review. For Laravel — l5-swagger or dedoc/scramble. For Node.js — @fastify/swagger or Zod + zod-to-openapi.

How to properly authenticate an API?

JWT with long-lived access tokens without rotation is a source of problems when compromised. The correct scheme: access token for 15 minutes, refresh token for 30 days with rotation on each use. Refresh token stored in an httpOnly cookie, access token in memory (not in localStorage). For inter-service communication — API Keys with scope limitations or mTLS. OAuth 2.0 with PKCE for public clients (SPA, mobile).

How to handle versioning and backward compatibility?

Breaking changes in an API without versioning break clients. Three approaches we use in projects:

We guarantee backward compatibility through automated checks (oasdiff) on CI.

How we develop APIs: step-by-step plan

1. Analysis — audit of current integrations, data schema compilation, protocol selection (REST/GraphQL/tRPC/WebSocket).
2. Contract design — OpenAPI or SDL (GraphQL) before the first line of code.
3. Development — implementation per contract, unit tests for each endpoint.
4. Load testing — k6: 500 virtual users, 10 minutes, p95 latency ≤ 200ms.
5. Deployment — CI/CD with backward compatibility check, automatic documentation publication.
6. Team training — handover of Postman collection or Playground, connection instructions.

What is included (deliverables)

• OpenAPI 3.1 specification (or SDL for GraphQL).
• Generated client types for TypeScript / Dart / Kotlin.
• Set of automated tests covering all endpoints (unit + integration).
• Load tests (k6) and report (p50/p95/p99 latency, RPS).
• Documentation in Swagger UI / Redoc / GraphiQL.
• Team training (2–4 hour workshop).
• Support for 30 days after delivery (per contract).

Our experience

• 10+ years in the API development market.
• 200+ completed projects (REST, GraphQL, WebSocket, tRPC).
• 50+ certified engineers (AWS, Kubernetes, API Design).
• Traffic savings averaging 85% when migrating from REST to GraphQL for mobile apps.
• 100% backward compatibility — not a single broken client in the last 3 years.

Timeline

API development for a typical SaaS project with 30–50 endpoints: from 3 to 8 weeks depending on business logic complexity and number of external integrations. Migration of an existing REST API to GraphQL: from 2 to 6 weeks. Adding a WebSocket layer to an existing backend: from 1 to 3 weeks. Cost is calculated individually after an audit. Get a consultation — contact us to discuss your project.