GraphQL — co to jest i jak działa?

GraphQL to język zapytań do API który daje klientowi pełną kontrolę nad danymi. Poznaj Query, Mutation, Subscription, schema SDL i kiedy wybrać GraphQL zamiast REST.

Czym jest GraphQL?

GraphQL to język zapytań do API stworzony przez Facebook w 2012 roku, open-sourcowany w 2015. Zamiast wielu endpointów REST, GraphQL oferuje jeden endpoint i pozwala klientowi precyzyjnie zdefiniować jakich danych potrzebuje — nie więcej, nie mniej.

GraphQL jest używany przez Facebook, GitHub, Twitter, Shopify, Airbnb i tysiące innych firm. Szczególnie wartościowy w aplikacjach z złożonymi, powiązanymi danymi i wieloma typami klientów (web, mobile, TV) o różnych wymaganiach dotyczących danych.

Stworzony przez

Facebook (Meta)

2012 (internal), 2015 (open-source)

Jeden endpoint

POST /graphql

Wszystkie operacje przez jeden URL

Typowany

Schema SDL

Kontrakt klient-serwer z pełną introspection

3 operacje GraphQL

Query

Operacja odczytu danych — odpowiednik GET w REST. Queries mogą być wykonywane równolegle.

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

Mutation

Operacja zapisu, aktualizacji lub usunięcia danych — odpowiednik POST/PUT/DELETE w REST. Mutacje wykonywane sekwencyjnie.

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    author {
      name
    }
  }
}

Subscription

Operacja real-time — klient subskrybuje zdarzenia. Serwer wysyła dane gdy zdarzenie nastąpi (WebSocket).

subscription OnNewMessage($channelId: ID!) {
  messageAdded(channelId: $channelId) {
    id
    text
    sender { name }
    createdAt
  }
}

GraphQL Schema (SDL)

Schema Definition Language (SDL) to język definiowania typów i operacji GraphQL. Schema jest kontraktem między klientem a serwerem — wszystko co nie jest w schema, nie istnieje.

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
  post(slug: String!): Post
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
  deletePost(id: ID!): Boolean!
}

type User {
  id: ID!
  name: String!
  email: String!
  role: UserRole!
  posts: [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  tags: [String!]!
  publishedAt: DateTime
}

enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

input CreateUserInput {
  name: String!
  email: String!
  role: UserRole = VIEWER
}

GraphQL vs REST — porównanie

Aspekt	GraphQL	REST API
Endpointy	Jeden endpoint: POST /graphql	Wiele endpointów: /users, /posts, /comments
Struktura danych	Klient definiuje dokładną strukturę w zapytaniu	Serwer definiuje stałą strukturę odpowiedzi
Over-fetching	Brak — pobierasz tylko potrzebne pola	Częsty — endpoint zwraca wszystkie pola zasobu
Under-fetching	Brak — jeden request pobiera wszystkie powiązane dane	Częsty — N+1 zapytań dla powiązanych zasobów
Typowanie	Strongly typed schema (SDL) — kontrakt klient-serwer	Opcjonalne (OpenAPI/Swagger) — często brak
Wersjonowanie	Brak tradycyjnego wersjonowania — schema evolution	URL versioning: /api/v1/, /api/v2/
Caching	Trudniejsze — POST, persisted queries, Apollo Cache	Łatwe — HTTP caching, CDN, ETag
Narzędzia	GraphiQL, Apollo Studio, GraphQL Playground	Swagger UI, Postman, curl

Ekosystem GraphQL

Apollo Client

Client-side

Najpopularniejsza biblioteka GraphQL dla React/JS. Zarządza state, caching, optymistic updates.

apollographql.com

Apollo Server

Server-side

Node.js GraphQL server. Obsługuje schema, resolvers, datasources, subscriptions.

apollographql.com

Relay

Client-side

Biblioteka React od Meta. Zaawansowany caching, pagination (Connections spec), compiler.

relay.dev

Hasura

Backend-as-a-Service

Automatycznie generuje GraphQL API z bazy danych PostgreSQL. Zero-code backend.

hasura.io

GraphQL Yoga

Server-side

Lekki, szybki GraphQL server od The Guild. Wsparcie dla subscriptions, file uploads.

the-guild.dev/graphql/yoga-server

URQL

Client-side

Lekka alternatywa dla Apollo Client. Modularny, mały bundle, łatwy w konfiguracji.

formidable.com/open-source/urql

FAQ — GraphQL

Co to jest GraphQL?

GraphQL to język zapytań do API oraz runtime do ich wykonywania, stworzony przez Facebook w 2012 roku i open-sourcowany w 2015. W przeciwieństwie do REST, GraphQL pozwala klientowi precyzyjnie określić jakich danych potrzebuje — nie więcej, nie mniej. Jeden endpoint (/graphql) obsługuje wszystkie operacje: Query (odczyt), Mutation (zapis) i Subscription (real-time). GraphQL jest typowany — schema definiuje dostępne typy i operacje.

Czym różni się GraphQL od REST API?

REST API: wiele endpointów (/users, /posts, /comments), fixed response structure, over-fetching (za dużo danych) lub under-fetching (za mało — N+1 problem), wersjonowanie przez URL (/v1/, /v2/). GraphQL: jeden endpoint (/graphql), klient definiuje strukturę danych, brak over/under-fetchingu, brak tradycyjnego wersjonowania (schema evolution przez deprecated fields). GraphQL lepszy dla złożonych, powiązanych danych; REST prostszy dla prostych CRUD API.

Co to jest GraphQL Schema?

GraphQL Schema (SDL — Schema Definition Language) to kontrakt między klientem a serwerem — definicja wszystkich dostępnych typów, pól, zapytań i mutacji. Schema jest typowana i samodokumentująca. Przykład: 'type User { id: ID!, name: String!, email: String!, posts: [Post!]! }'. Schema First Development: najpierw definiujesz schema, potem implementujesz resolvers. Introspection pozwala narzędziom (GraphiQL) na automatyczne generowanie dokumentacji.

Co to są resolvers w GraphQL?

Resolvers to funkcje po stronie serwera GraphQL, które faktycznie pobierają dane dla każdego pola w schema. Dla każdego pola można zdefiniować resolver — funkcję (parent, args, context, info) => data. Jeśli resolver nie jest zdefiniowany, GraphQL użyje domyślnego (zwraca pole z parent object). N+1 problem w resolverach rozwiązuje się przez DataLoader (batching i caching żądań do bazy danych).

Kiedy używać GraphQL zamiast REST?

GraphQL jest lepszy gdy: aplikacja ma złożone, powiązane dane (social network, e-commerce z wariantami), wiele różnych klientów (mobile, web, TV) o różnych potrzebach danych, chcesz uniknąć over-fetchingu, budujesz BFF (Backend for Frontend). REST jest lepszy gdy: proste CRUD API, publiczne API dla zewnętrznych developerów (REST bardziej znajomy), potrzebujesz prostego cachowania HTTP, masz ograniczony czas — REST szybszy w implementacji.

Czytaj dalej