GraphQL (Query Language for APIs)

GraphQL is an open-source data query and manipulation language for application programming interfaces (APIs) and a runtime for executing queries with existing data. Developed internally by Facebook (Meta) in 2012 and released publicly in 2015, GraphQL provides a complete and understandable description of the data in your API, empowering clients to request exactly what they need and nothing more.

Construct queries interactively with our GraphQL Query Builder or generate type-safe definitions directly with GraphQL to TypeScript.

---

Technical Specifications at a Glance

Specification	Details
Current Specification	GraphQL Specification (Governed by GraphQL Foundation / Linux Foundation)
MIME Media Type	application/graphql+json, application/json
Standard File Extensions	.graphql, .gql
Transport Protocol	HTTP POST (Typically over /graphql endpoint)
Serialization Format	Responses serialized as JSON
Type System Model	Strongly typed Schema Definition Language (SDL)

---

The 3 Core GraphQL Operations

GraphQL APIs process three foundational operations:

1. Queries (query): Read-only fetch operations analogous to REST GET requests:

   query GetUserAndTools($userId: ID!) {
     user(id: $userId) {
       name
       email
       favoriteTools {
         slug
         category
       }
     }
   }
   

2. Mutations (mutation): State-modifying operations analogous to POST, PUT, or DELETE:

   mutation AddBookmark($toolSlug: String!) {
     addBookmark(slug: $toolSlug) {
       success
       updatedAt
     }
   }
   

3. Subscriptions (subscription): Real-time bidirectional streaming connections (via WebSockets or Server-Sent Events) that push data to the client whenever server events occur.

---

GraphQL vs REST: Architectural Comparison

Architectural Feature	GraphQL	REST (Representational State Transfer)
Data Fetching Precision	Exact: No over-fetching or under-fetching	Fixed endpoints often return redundant fields
Round Trips	Single request can query nested relational resources	Multiple waterfall HTTP requests (/users, /posts)
Endpoints	Single unified endpoint (e.g. POST /graphql)	Multiple resource URLs (/api/v1/users, /api/v1/posts)
HTTP Caching	Complex (often handled via client-side Apollo/Relay cache)	Simple and native via standard HTTP Cache-Control
API Versioning	Continuous evolution via field deprecation (@deprecated)	Versioned URL paths (/v1/, /v2/)

---

Schema Definition Language (SDL)

GraphQL APIs are contract-driven. The entire capability of the backend is declared in a strongly typed schema:

type Tool {
  id: ID!
  slug: String!
  name: String!
  description: String
  category: ToolCategory!
  isFree: Boolean!
}

enum ToolCategory {
  SECURITY
  DATA_FORMATS
  WEB_CODE
}

type Query {
  tool(slug: String!): Tool
  allTools(category: ToolCategory): [Tool!]!
}

---

Frequently Asked Questions

What is over-fetching and under-fetching?

• Over-fetching: A REST endpoint returns a large JSON object with 30 fields when the client only needed the user's username.
• Under-fetching: A REST endpoint returns too little data, forcing the client to make 3 additional sequential HTTP requests to retrieve related entities. GraphQL completely solves both problems by allowing the client's query to dictate the exact response structure.

How does GraphQL handle error reporting?

Unlike REST, which signals errors using HTTP status codes (404 Not Found, 400 Bad Request), a GraphQL server generally returns an HTTP 200 OK status with a top-level JSON response containing both data and an errors array detailing execution errors.

Can I generate TypeScript types from a GraphQL schema?

Yes. Manually duplicating GraphQL schemas into TypeScript interfaces leads to type drift and runtime bugs. You can paste your GraphQL schema or query into our GraphQL to TypeScript tool to generate end-to-end type-safe models instantly.