TLDR
GraphQL is all about hooking you up with exactly what you need. Whether you’re using a mobile or a web app, it lets you to request only the specific fields or properties that you’re interested in. That way, you don’t end up fetching a bunch of unnecessary data. It’s like solving the problem of both overfetching and underfetching at the same time. You can snag multiple resources in just one request. Pretty slick, right?
I can’t be the only dude into REST-APIs who had a tough time getting my head around GraphQL terminologies at first, man. It’s like the GraphQL crew went all out to come up with their own fancy terms and names, even though the REST-API scene already had ‘em covered. Seriously, GraphQL, why you gotta be so extra? 🙄
Anyway, this cheat sheet is for both of us, haha! I know I’ll definitely need it in the future when I forget what some fancy GraphQL term means.
Starting from the Basics
What is Graphql?
Think of it as a query language for your APIs, kind of like an SQL for querying your backend APIs. In most tech stacks, we usually have a bunch of microservices and monoliths that are responsible for handling different kinds of data and resources. GraphQL pretty much sits in between those APIs and your client application, like a middleware, getting and updating data to and fro.
Graphql is designed so the client (mobile or web app) can request only the fields - properties that they need. For this reason it prevents overfetching of data that will not actually be used and also solves under fetching because you can get many different resources in one single request.
Ok let’s unpack the Graphql lingo now that we understand what it does and why we need it in the first place.
Schema
schema = clear contract between server and client
schemas fully describes your GrpahQL API is and what it is capable of. Think of the types, queries, interfaces and fields that it supports. Basically a map / snapshot of everything your Graph Supports.
What does it look like
1
2
3
4
5
6
7
8
9
type Query {
getUser(id: ID!): User
}
type User {
id: ID!
name: String!
email: String!
}
In this schema we have a Query type with a single field getUser that takes an id parameter and returns a User object. The User object has fields like id, name, and email.
Query
Query = Read Operation. Nothing special just the equivalent of a GET request in REST APIs. Except in graphql queries we generally make a POST Request even when we want to GET a resource. It’s basically a client POSTING some JSON (aka query) to graphql server and the server sending some JSON back as response. All what graphql clients do is make HTTP requests, there is nothing magical about them.
What does it look like
1
2
3
4
5
6
query {
getUser(id: "123") {
name
email
}
}
For this query, we’re requesting the name and email fields of a user with the ID “123”. The response from the server will only include the name and email fields. Again this is just the equivalent of a GET request in REST.
Mutation
Mutation = Write Operation. Basically a create, update, or delete operation followed by fetch operation. A mutation is when when you perform a write operation and then fetch the result.
What does it look like
1
2
3
4
5
6
7
mutation {
createUser(name: "John Doe", email: "[email protected]") {
id
name
email
}
}
In this mutation, we’re creating a new user with the name “John Doe” and email “[email protected]”. The response from the server will include the ID, name, and email of the newly created user.
Built-in Scalars
Scalars = Primitive Data types.
GraphQL has a set of built-in scalars that we can use to represent basic data types. These scalars include Int, Float, String, Boolean, and ID. You can use these scalars in your type definitions to specify the type of a field.
What does it look like
1
2
3
4
5
6
7
type Post {
id: ID!
title: String!
views: Int
isPublished: Boolean!
createdAt: String
}
Here all we have is a Post type with fields like id, title, views, isPublished, and createdAt. The String, Int, and Boolean scalars are used to specify the types of these fields.
Type Definitions
Type Definitions = Data Model just like a struct or class in swift
In GraphQL, sometimes we need to define a type, the equivalent of a struct or class in swift to define the structure of our data. We define these custom types in GraphQL using the Type Definition. Types can have fields that represent different properties of the data.
What does it look like
1
2
3
4
5
6
type Book {
id: ID!
title: String!
author: String!
publicationYear: Int
}
Just think of the above as a Book struct in swift with id, title, author, and publicationYear properties.
Type Modifiers
Type Modifiers are Generally just a way for us to specify if a field can be optional or non optional
These operators allow us to apply additional constraints on fields. Sometimes we need to indicate that a field is optional or non optional. Some common type modifiers include ! which means the field is (non-null), [T] (list of type T), and [T!]! (non-null list of non-null type T).
What does it look like?
1
2
3
4
5
6
7
type User {
id: ID!
name: String!
email: String!
posts: [Post]
favoriteBooks: [Book!]!
}
You can think of this as a struct data model in swift with the id, name, and email fields being non optionals, meaning they must always have a value. While the posts field is a nullable list of Post objects, and the favoriteBooks field is a non-null list of non-null Book objects.
Conclusion
GraphQL may have its own set of fancy terms, but once you get the hang of them, it’s a powerful tool for APIs. With the ability to request only the necessary data we need, GraphQL eliminates the hassle of overfetching and underfetching, making apps more performant and responsive, at least in theory 😂 lol, any tool can be mismanaged and GQL is no exception. But, don’t be intimidated by the jargon—embrace GraphQL and level up your API game!