GraphQL CheatSheet

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.

---

An alternative approach to RESTful APIs

GraphQL is a query language for APIs

Easily describe the shape of the GraphQL API using clear shared terms.

Clients issue queries/mutations to read and update data

GraphQL syntax can express complex entity relations

Libraries to implement GraphQL in different languages

Copyright 2015?present, Facebook, Inc.

As of September 26, 2017, the following persons or entities have made this Specification available under the Open Web Foundation Final Specification Agreement (OWFa 1.0), which is available at openwebfoundation.org.

• Hierarchical: Most product development today involves the creation and manipulation of view hierarchies. To achieve congruence with the structure of these applications, a GraphQL query itself is structured hierarchically. The query is shaped just like the data it returns. It is a natural way for clients to describe data requirements.
• Product?centric: GraphQL is unapologetically driven by the requirements of views and the front?end engineers that write them. GraphQL starts with their way of thinking and requirements and builds the language and runtime necessary to enable that.
• Strong?typing: Every GraphQL server defines an application?specific type system. Queries are executed within the context of that type system. Given a query, tools can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at development time, and the server can make certain guarantees about the shape and nature of the response.
• Client?specified queries: Through its type system, a GraphQL server publishes the capabilities that its clients are allowed to consume. It is the client that is responsible for specifying exactly how it will consume those published capabilities. These queries are specified at field?level granularity. In the majority of client?server applications written without GraphQL, the server determines the data returned in its various scripted endpoints. A GraphQL query, on the other hand, returns exactly what a client asks for and no more.
• Introspective: GraphQL is introspective. A GraphQL servers type system must be queryable by the GraphQL language itself, as will be described in this specification. GraphQL introspection serves as a powerful platform for building common tools and client software libraries.

Being less "talkative" than REST makes GraphQL way faster, as you can cut down on your request by picking only the fields you want to query. The following list shows other major advantages of using a GraphQL API in an application instead of a REST API.

• Good fit for complex systems and microservices.
• Fetching data with a single API call.
• No over- and under-fetching problems.
• Tailoring requests to your needs.
• Validation and type checking out-of-the-box.
• Autogenerating API documentation.
• API evolution without versioning.
• Code-sharing.
• Detailed error messages.
• Permissions.
• An additional operation.
• Rapid application prototyping.

Although GraphQL is a decent alternative to REST, its not a replacement yet. Wed like to point out that sending data-specific queries can be also implemented in REST with the help of many JSON API libraries. For using a schema and strong types in REST, JSON schemas will come in handy. On the other hand, implementing these libraries can be complicated and thats why using GraphQL might be a better idea, as it natively supports all of these features.

• Performance issues with complex queries.
• Overkill for small applications.
• Web caching complexity.
• File uploading.
• Takes a while to understand.

GraphQL works best for the following scenarios:

• Apps for devices such as mobile phones, smartwatches, and IoT devices, where bandwidth usage matters.

• Applications where nested data needs to be fetched in a single call.
  • For example, a blog or social networking platform where posts need to be fetched along with nested comments and commenters details.
• Composite pattern, where application retrieves data from multiple, different storage APIs
  • For example, a dashboard that fetches data from multiple sources such as logging services, backends for consumption stats, third-party analytics tools to capture end-user interactions.
• Proxy pattern on client side; GraphQL can be added as an abstraction on an existing API, so that each end-user can specify response structure based on their needs.
  • For example, clients can create a GraphQL specification according to their needs on common API provided by FireBase as a backend service.

Basic Input

    
type Query {
    users(limit: Int): [User]
}
    

---

Input with default value

    
type Query {
    users(limit: Int = 10): [User]
}
    

---

Input with multiple arguments

    
type Query {
    users(limit: Int, sort: String): [User]
}
    

---

Input with multiple arguments and default values

    
type Query {
    users(limit: Int = 10, sort: String): [User]
}
    

---

    
type Query {
    users(limit: Int, sort: String = "asc"): [User]
}
    

---

    
type Query {
    users(limit: Int = 10, sort: String = "asc"): [User]
}
    

input ListUsersInput {
    limit: Int
    since_id: ID
}

// --------------
type Mutation {
    users(params: ListUsersInput): [User]!
}

scalar Url
type User {
    name: String
    homepage: Url
}

interface Foo {
    is_foo: Boolean
}


interface Goo {
    is_goo: Boolean
}


type Bar implements Foo {
    is_foo: Boolean
    is_bar: Boolean
}


type Baz implements Foo, Goo {
    is_foo: Boolean
    is_goo: Boolean
    is_baz: Boolean
}

type Foo {
    name: String
}


type Bar {
    is_bar: String
}


union SingleUnion = Foo
union MultipleUnion = Foo | Bar
type Root {
    single: SingleUnion
    multiple: MultipleUnion
}

enum USER_STATE {
    NOT_FOUND
    ACTIVE
    INACTIVE
    SUSPENDED
}


type Root {
    stateForUser(userID: ID!): USER_STATE!
    users(state: USER_STATE, limit: Int = 10): [User]
}