What is GraphQL?

GraphQL is a query language for APIs and a server-side runtime that returns exactly the fields each client asks for in one request. The duality matters: the language is a specification any client can speak; the runtime executes those queries against a type system you define over your existing data — any database, any service. It is not a database, and it replaces neither your storage nor, necessarily, your REST API.

Key takeaways

The signature demo: query and response

The demo every explanation converges on, because it is the idea — the response is the query, filled in:

# Request                              # Response
{                                      {
  post(id: "8fk2") {                     "data": {
    title                                  "post": {
    author {                                 "title": "Hello GraphQL",
      username                               "author": {
    }                                          "username": "ada"
    comments(first: 2) {                     },
      text                                   "comments": [
    }                                          { "text": "Nice." },
  }                                            { "text": "Ship it." }
}                                            ]
                                           }
                                         }
                                       }

One request, three related resources, zero unrequested fields — the overfetching and underfetching pair retired in a stroke. Calling it from real clients is plain HTTP:

// JavaScript / Node.js — query Back4app's auto-generated GraphQL API
const res = await fetch('https://parseapi.back4app.com/graphql', {
  method: 'POST',
  headers: {
    'X-Parse-Application-Id': APP_ID,
    'X-Parse-Client-Key': CLIENT_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: '{ posts(first: 20) { edges { node { title author { username } } } } }',
  }),
});
const { data } = await res.json(); // shaped exactly like the query

// Flutter / Dart — query Back4app's auto-generated GraphQL API
final res = await http.post(
  Uri.parse('https://parseapi.back4app.com/graphql'),
  headers: {
    'X-Parse-Application-Id': appId,
    'X-Parse-Client-Key': clientKey,
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'query': '{ posts(first: 20) { edges { node { title author { username } } } } }',
  }),
);
final data = jsonDecode(res.body)['data']; // shaped exactly like the query

// iOS / Swift — query Back4app's auto-generated GraphQL API
var request = URLRequest(url: URL(string: "https://parseapi.back4app.com/graphql")!)
request.httpMethod = "POST"
request.setValue(appId, forHTTPHeaderField: "X-Parse-Application-Id")
request.setValue(clientKey, forHTTPHeaderField: "X-Parse-Client-Key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let query = "{ posts(first: 20) { edges { node { title author { username } } } } }"
request.httpBody = try JSONEncoder().encode(["query": query])
let (data, _) = try await URLSession.shared.data(for: request)
// data is shaped exactly like the query

// Android / Kotlin — query Back4app's auto-generated GraphQL API
val body = """{ "query": "{ posts(first: 20) { edges { node { title author { username } } } } }" }"""
val request = Request.Builder()
    .url("https://parseapi.back4app.com/graphql")
    .addHeader("X-Parse-Application-Id", APP_ID)
    .addHeader("X-Parse-Client-Key", CLIENT_KEY)
    .post(body.toRequestBody("application/json".toMediaType()))
    .build()
val data = client.newCall(request).execute().body?.string() // shaped like the query

Schema, query, resolver: the working trio

Explainers show the query; almost none show the machinery behind it as one coherent picture. The schema is the typed contract, written in SDL:

type Post {
  title: String!          # ! = non-null
  author: User!
  comments(first: Int): [Comment!]
}

type Query {              # the read entry points
  post(id: ID!): Post
}

type Mutation {           # the write entry points
  createPost(title: String!): Post!
}

Resolvers are the runtime’s other half — one function per field, each free to fetch from anywhere:

const resolvers = {
  Query: {
    post: (_, { id }) => db.posts.findById(id),
  },
  Post: {
    author: (post) => db.users.findById(post.authorId),   // called per post!
  },
};

Execution is a pipeline: parse the query, validate it against the schema (invalid operations die before touching data), then walk the selection set calling resolvers and assemble the mirrored JSON. That per-field resolver call is also the flexibility’s price tag — note the // called per post!, which becomes the N+1 problem below. The name, which nobody explains: your data forms a graph of typed objects, and queries traverse it from root fields — though only along schema-exposed paths, not arbitrary traversals like a true graph query language.

Provenance, briefly: created at Facebook (now Meta) in 2012 for its mobile apps, open-sourced in 2015, governed since 2018 by the GraphQL Foundation under the Linux Foundation, current spec edition October 2021, with a GraphQL-over-HTTP draft standardizing the transport conventions.

Queries, mutations, subscriptions

Queries read. Mutations write — and select fields on the result, so the client gets the post-write state in the same round trip. Subscriptions keep a connection open (in practice WebSockets) and push events as they occur; they are GraphQL’s real-time story, with the caveat that each active subscription is server-held state. All three share the schema, the type system, and the tooling — one contract, three tenses.

GraphQL vs. REST

The full argument — including when REST is simply the better choice — lives in the dedicated GraphQL vs. REST entry.

Running GraphQL in production: the honest costs

The section vendor explainers soften. Caching: one POST endpoint forfeits URL-keyed HTTP and CDN caching; the replacement is client-side normalized caches keyed on id plus __typename, and persisted queries (safe-listed, hashed operations sent as GETs) to win some transport caching back. N+1: naive resolvers turn a 20-post list into 1 + 20 database reads — the same problem REST clients have over HTTP, relocated to your resolver layer, and fixed there by batching loaders like DataLoader. Errors: GraphQL returns 200 OK with an errors array — monitoring keyed on status codes goes blind unless taught otherwise. Rate limiting: requests are not equal when one query can nest ten relations; mature APIs meter query cost (depth and complexity analysis), not request count. Security: disable introspection in production, enforce depth and complexity limits, and keep authorization in the business layer under the resolvers — the single endpoint also blinds URL-based WAF rules, so validation moves into the GraphQL layer itself.

Common use cases

• Mobile apps on constrained networks — the founding use case: exact fields, minimal bytes, fewer round trips.
• Multi-client products — watch app, phone app, web dashboard, each shaping its own responses against one schema.
• Backend-for-frontend aggregation — one GraphQL layer composing several internal services for consumption by UIs.
• Rapidly evolving frontends — new screens select new fields without waiting for new endpoints.
• Typed contracts end to end — schema introspection generating typed clients, keeping API and UI honest at compile time.

Should you use GraphQL? A decision matrix

Limitations and trade-offs

• The flexibility is server-paid. Arbitrary client queries mean the server must be safe under any shape — batching, cost limits, and depth guards are prerequisites, not polish.
• Caching becomes your project. What HTTP gave REST for free, GraphQL teams reimplement in client caches and persisted queries.
• Observability needs relearning. One endpoint, always-200 responses, and per-field timing require GraphQL-aware tooling.
• File uploads and binary data are awkward — commonly delegated to separate upload endpoints beside the graph.
• Schema governance is organizational. A shared contract across teams needs ownership rules; federation (composing team-owned subgraphs into one supergraph) is the scaling answer, and its own discipline.

GraphQL on Back4app

Back4app is an open-source Backend-as-a-Service (BaaS) platform that combines a managed database, auto-generated REST and GraphQL APIs, authentication, file storage, and Cloud Code serverless functions. The distinctive part is where the schema comes from: define a data model and the platform generates the GraphQL API — typed object types, query and mutation fields, relation-traversing connections like the posts → author example above — with no resolvers to write, since Back4app implements them against your database with permissions enforced per request. The code tabs show the whole client story: one POST to /graphql with your app’s keys. A built-in GraphQL console covers exploration, REST remains available on the same data for cache-friendly reads, and custom logic joins the schema as Cloud Code functions — the honest-costs section above becomes largely the platform’s bill, not yours.