GraphQL | A query language for your API

?? GraphQLConf 2024 ? Sept 10-12 ? San Francisco ? Schedule Coming Soon! ? Read more

GraphQL

Describe your data

type
 Project
 {

  name
: 
String

  tagline
: 
String

  contributors
: [
User
]

}

Ask for what you want

{

  project
(
name
: 
"GraphQL"
) {

    tagline

  }

}

Get predictable results

{

  "project"
: {

    "tagline"
: 
"A query language for APIs"

  }

}

Get Started

A query language for your API

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

Ask for what you need,
get exactly that

Send a GraphQL query to your API and get exactly what you need, nothing more and nothing less. GraphQL queries always return predictable results. Apps using GraphQL are fast and stable because they control the data they get, not the server.

Get many resources
in a single request

GraphQL queries access not just the properties of one resource but also smoothly follow references between them. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request. Apps using GraphQL can be quick even on slow mobile network connections.

{

  hero
 {

    name

    friends
 {

      name

    }

  }

}

{

  "hero"
: {

    "name"
: 
"Luke Skywalker"
,

    "friends"
: [

      { 
"name"
: 
"Obi-Wan Kenobi"
 },

      { 
"name"
: 
"R2-D2"
 },

      { 
"name"
: 
"Han Solo"
 },

      { 
"name"
: 
"Leia Organa"
 }

    ]

  }

}

Describe what's possible
with a type system

GraphQL APIs are organized in terms of types and fields, not endpoints. Access the full capabilities of your data from a single endpoint. GraphQL uses types to ensure Apps only ask for what's possible and provide clear and helpful errors. Apps can use types to avoid writing manual parsing code.

Query

{

  hero
 {

    name

    friends
 {

      name

      homeWorld
 {

        name

        climate

      }

      species
 {

        name

        lifespan

        origin
 {

          name

        }

      }

    }

  }

}

Schema

type
 Query
 {

  hero
: 
Character

}

 
type
 Character
 {

  name
: 
String

  friends
: [
Character
]

  homeWorld
: 
Planet

  species
: 
Species

}

 
type
 Planet
 {

  name
: 
String

  climate
: 
String

}

 
type
 Species
 {

  name
: 
String

  lifespan
: 
Int

  origin
: 
Planet

}

Move faster with powerful developer tools

Know exactly what data you can request from your API without leaving your editor, highlight potential issues before sending a query, and take advantage of improved code intelligence. GraphQL makes it easy to build powerful tools like Graph i QL by leveraging your API’s type system.

Evolve your API
without versions

Add new fields and types to your GraphQL API without impacting existing queries. Aging fields can be deprecated and hidden from tools. By using a single evolving version, GraphQL APIs give apps continuous access to new features and encourage cleaner, more maintainable server code.

type
 Film
 {

  title
: 
String

  episode
: 
Int

  releaseDate
: 
String

}

type
 Film
 {

  title
: 
String

  episode
: 
Int

  releaseDate
: 
String

  openingCrawl
: 
String

}

type
 Film
 {

  title
: 
String

  episode
: 
Int

  releaseDate
: 
String

  openingCrawl
: 
String

  director
: 
String

}

type
 Film
 {

  title
: 
String

  episode
: 
Int

  releaseDate
: 
String

  openingCrawl
: 
String

  director
: 
String

  directedBy
: 
Person

}

 
type
 Person
 {

  name
: 
String

  directed
: [
Film
]

  actedIn
: [
Film
]

}

type
 Film
 {

  title
: 
String

  episode
: 
Int

  releaseDate
: 
String

  openingCrawl
: 
String

  director
: 
String
 @deprecated

  directedBy
: 
Person

}

 
type
 Person
 {

  name
: 
String

  directed
: [
Film
]

  actedIn
: [
Film
]

}

Bring your own data and code

GraphQL creates a uniform API across your entire application without being limited by a specific storage engine. Write GraphQL APIs that leverage your existing data and code with GraphQL engines available in many languages. You provide functions for each field in the type system, and GraphQL calls them with optimal?concurrency.

GraphQL

type
 Character
 {

  name
: 
String

  homeWorld
: 
Planet

  friends
: [
Character
]

}

JavaScript

// type Character {

class
 Character
 {

  // name: String

  getName
() {

    return
 this
._name

  }

  // homeWorld: Planet

  getHomeWorld
() {

    return
 fetchHomeworld
(
this
._homeworldID)

  }

  // friends: [Character]

  getFriends
() {

    return
 this
._friendIDs.
map
(fetchCharacter)

  }

}

Python

# type Character {

class
 Character
:

  # name: String

  def
 name
(self):

    return
 self
._name

 
  # homeWorld: Planet

  def
 homeWorld
(self):

    return
 fetchHomeworld(
self
._homeworldID)

 
  # friends: [Character]

  def
 friends
(self):

    return
 map
(fetchCharacter, 
self
._friendIDs)

C Sharp

// type Character {

public
 class
 Character
 {

  // name: String

  public
 String
 Name
 { 
get
; }

 
  // homeWorld: Planet

  public
 async
 Task
<
Planet
> 
GetHomeWorldAsync
() {

    return
 await
 FetchHomeworldAsync
(_HomeworldID);

  }

 
  // friends: [Character]

  public
 async
 IEnumerable
<
Task
<
Character
>> 
GetFriendsAsync
() {

    return
 _FriendIDs.
Select
(FetchCharacterAsync);

  }

}

GraphQL

type
 Character
 {

  name
: 
String

  homeWorld
: 
Planet

  friends
: [
Character
]

}

JavaScript

// type Character {

class
 Character
 {

  // name: String

  getName
() {

    return
 this
._name

  }

  // homeWorld: Planet

  getHomeWorld
() {

    return
 fetchHomeworld
(
this
._homeworldID)

  }

  // friends: [Character]

  getFriends
() {

    return
 this
._friendIDs.
map
(fetchCharacter)

  }

}

Python

# type Character {

class
 Character
:

  # name: String

  def
 name
(self):

    return
 self
._name

 
  # homeWorld: Planet

  def
 homeWorld
(self):

    return
 fetchHomeworld(
self
._homeworldID)

 
  # friends: [Character]

  def
 friends
(self):

    return
 map
(fetchCharacter, 
self
._friendIDs)

C Sharp

// type Character {

public
 class
 Character
 {

  // name: String

  public
 String
 Name
 { 
get
; }

 
  // homeWorld: Planet

  public
 async
 Task
<
Planet
> 
GetHomeWorldAsync
() {

    return
 await
 FetchHomeworldAsync
(_HomeworldID);

  }

 
  // friends: [Character]

  public
 async
 IEnumerable
<
Task
<
Character
>> 
GetFriendsAsync
() {

    return
 _FriendIDs.
Select
(FetchCharacterAsync);

  }

}

Who's using GraphQL?

Facebook's mobile apps have been powered by GraphQL since 2012. A GraphQL spec was open sourced in 2015 and is now available in many environments and used by teams of all sizes.