An Introduction to GraphQL

GraphQL is a query language used for API development and comes with server-side runtimes implemented in various backend languages. It is not tied to any specific technology, allowing it to be implemented in any language. GraphQL introduces a new approach to API design and directly competes with traditional REST APIs, similar to how REST initially competed with SOAP.

Developed at Facebook, GraphQL was publicly launched in 2015, but Facebook had used it internally before that. Since then, many big companies such as GitHub, Pinterest, Twitter, and The New York Times have adopted GraphQL alongside Facebook.

How it Works:

In GraphQL, you have a single endpoint from your server. You send a query to this endpoint using the GraphQL Query Language syntax. This query is in the form of a string. The server responds to the query by returning a JSON object.

Example:

GET /graphql?query={ person(id: "1") { name } }

or

{
 person(id: "1") {
 name
 }
}

This query returns the name of a person with the ID of 1:

{
 "name": "Tony"
}

You can make the query more complex by retrieving additional details, such as the city where the person lives:

GET /graphql?query={ person(id: "1") { name, address { city } } }

or

{
 person(id: "1") {
 name
 address {
 city
 }
 }
}

This query returns the name of the person and their city:

{
 "name": "Tony",
 "address": {
 "city": "York"
 }
}

GraphQL Queries:

In GraphQL queries, you can include various elements such as fields, arguments, aliases, and fragments.

Fields and Arguments:

A GraphQL query consists of fields and arguments. Fields represent the data you want to retrieve, and arguments allow you to specify custom queries. For example:

{
 person(id: "1") {
 name
 }
}

This query retrieves the name of a person with the ID of 1.

Aliases:

Aliases allow you to give different names to fields. This is useful when you need to reference the same endpoint multiple times in a query:

{
 owner: person(id: "1") {
 fullname: name
 }
}

This query returns the name of a person with the ID of 1 as “fullname” under the owner field.

Fragments:

Fragments allow you to specify the structure of a query once and reuse it in multiple places:

{
 owner: person(id: "1") {
 ...personFields
 }
 first_employee: person(id: "2") {
 ...personFields
 }
}

fragment personFields on person {
 fullname: name
}

GraphQL Variables:

GraphQL queries can use variables to dynamically specify values. This is useful when you need to pass values that may change. Variables are defined within the query and can have types, default values, and can be required or optional.

Making Variables Required:

Appending a “!” to the type of a variable makes it required:

query GetOwner($id: String!)

Specifying a Default Value for a Variable:

You can specify a default value for a variable using the syntax:

query GetOwner($id: String = "1")

GraphQL Directives:

Directives in GraphQL allow you to include or exclude fields based on the value of a variable.

@include(if: Boolean):

Include a field if a certain condition is true:

query GetPerson($id: String) {
 person(id: $id) {
 fullname: name,
 address: @include(if: $getAddress) {
 city
 street
 country
 }
 }
}

{
 "id": "1",
 "getAddress": false
}

@skip(if: Boolean):

Skip a field if a certain condition is true:

query GetPerson($id: String) {
 person(id: $id) {
 fullname: name,
 address: @skip(if: $excludeAddress) {
 city
 street
 country
 }
 }
}

{
 "id": "1",
 "excludeAddress": false
}

Tags: GraphQL, API, query language, REST, CRUD, server-side runtimes, directives, variables, schema, fields, arguments, aliases, fragments