GraphQL

Query language and runtime for APIs. Single endpoint (usually POST /graphql); the client describes exactly the shape of data it wants.

Operations

Three operation types: query (read), mutation (write), subscription (stream).

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

Sent as JSON:

{
  "query":     "query GetUser($id: ID!) { user(id: $id) { id name email } }",
  "variables": { "id": "42" },
  "operationName": "GetUser"
}

Fields, arguments, aliases

{
  # Argument
  user(id: "42") { name }
 
  # Alias — rename a field in the response
  admin: user(id: "1") { name }
  guest: user(id: "2") { name }
}

Fragments (DRY)

fragment UserCore on User {
  id
  name
  avatarUrl
}
 
query {
  me   { ...UserCore }
  team { members { ...UserCore } }
}

Inline fragments (polymorphism)

{
  search(text: "foo") {
    __typename
    ... on User    { name }
    ... on Post    { title }
    ... on Comment { body }
  }
}

Variables and directives

query Posts($limit: Int = 10, $withAuthor: Boolean!) {
  posts(limit: $limit) {
    id
    title
    author @include(if: $withAuthor) { name }
    draft  @skip(if: $withAuthor)
  }
}

Built-in directives: @include(if:), @skip(if:), @deprecated(reason:).

Mutations

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    post   { id slug }
    errors { field message }
  }
}

Mutations at the top level run serially; query fields run in parallel.

Subscriptions

subscription OnMessage($roomId: ID!) {
  messageAdded(roomId: $roomId) {
    id
    text
    sender { name }
  }
}

Transport: WebSocket (graphql-ws protocol) or SSE.

Schema Definition Language (SDL)

"User of the system."
type User implements Node {
  id:      ID!
  name:    String!
  email:   String
  posts(first: Int = 10, after: String): PostConnection!
  role:    Role!
}
 
interface Node { id: ID! }
 
union SearchResult = User | Post | Comment
 
enum Role { ADMIN EDITOR VIEWER }
 
input CreatePostInput {
  title: String!
  body:  String!
  tags:  [String!] = []
}
 
type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
}
 
type Query {
  user(id: ID!): User
  posts(first: Int, after: String): PostConnection!
}
 
type Subscription {
  messageAdded(roomId: ID!): Message!
}
 
schema {
  query:        Query
  mutation:     Mutation
  subscription: Subscription
}

Scalars

Built-in: Int, Float, String, Boolean, ID. Custom scalars (e.g. DateTime, URL, JSON) are common but transport as strings.

Type modifiers:

Notation	Meaning
String	nullable string
String!	non-null string
[String]	nullable list of nullable strings
[String!]	nullable list of non-null strings
[String]!	non-null list of nullable strings
[String!]!	non-null list of non-null strings

Pagination (Relay-style cursors)

{
  posts(first: 10, after: "cursor") {
    edges {
      cursor
      node { id title }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Errors

Standard response shape:

{
  "data":   { "user": null },
  "errors": [
    { "message": "Not found",
      "path":    ["user"],
      "locations": [{ "line": 2, "column": 3 }],
      "extensions": { "code": "NOT_FOUND" } }
  ]
}

data and errors can both be present (partial results).

Introspection

Every GraphQL server exposes its own schema:

{ __schema { types { name kind } } }
{ __type(name: "User") { fields { name type { name kind } } } }
{ __typename }                     # works inside any selection set

Disable in production for closed APIs.

Querying from the CLI

# Basic POST
curl -s https://api.example.com/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ me { id name } }"}'
 
# With variables
curl -s https://api.example.com/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query($id:ID!){user(id:$id){name}}","variables":{"id":"42"}}'
 
# GET (read-only, query in URL)
curl -G https://api.example.com/graphql \
  --data-urlencode 'query={ me { id name } }'

Tooling: graphql-cli, gql, Insomnia, Postman, Apollo Sandbox, GraphiQL.

Best practices

• Use persisted queries in production (client sends a hash, server has the text) — cuts payload size and locks the surface.
• Add a query depth/complexity limit server-side to prevent abusive nested queries.
• Prefer input types for mutation arguments — easier to evolve.
• Return payload types from mutations with a errors field for typed user errors (don’t conflate with transport errors).
• Use @deprecated(reason:) instead of removing fields; clean up later.
• Don’t expose internal IDs as ID — opaque global IDs (base64-encoded) are convention.