This content originally appeared on DEV Community and was authored by Michael De Abreu
I'm not an expert in GraphQL, and this introduction it's most likely to be for my-future-self.
So, this weekend I spend it working on GraphQL, and I want to share my experience with it because it was hard for me to understand what was happening.
What is GraphQL?
GraphQL is a query language for APIs. This is prompted to be used as a substitute for RESTful, but I think you would be safe using those two together, as they probably won't interfere with each other.
The main difference between REST and GraphQL is that in REST you request a specific resource, and in GraphQL you made a query with the resources you want. Think like SQL, but in a declarative way, and for the web.
Why is GraphQL so popular?
I think is because it allows you to select the data you want to show, instead of making multiple requests for the same data.
I started to play with this because my brother built a Pokedex-like app, and it is really confusing the number of requests you need to make in order to show all the information you need. There is a lot of data.
How to work with GraphQL?
This is where I got lost. The official tutorial tries to teach you the definitions of things that you don't know what are. And it is really confusing, but I don't think it should be.
Start with your schema
Schemas are the answer, when "What data is needed?" is the question.
A schema is the shape of the things that you'll be querying. Even the Query itself needs a schema to know what should it returns when you query for something, but we will return to that in a second. There are multiple tools to create and declare your schema. In the standard .graphql file, the pokemon would be something like:
type Pokemon {
id: ID!
identifier: String
height: Int
weight: Int
base_experience: Int
order: Int
is_default: Int
image: String
alternativeForms: [Pokemon]
}
As you see, I define a Pokemon schema, with all the properties a Pokemon has. But also, I'm defining a Query schema. That schema is the one I will use to send my queries.
You can notice that it's not a replacement for the PokeAPI, so sorry if that disappoints you.
User defined types
As you can see, in the example we are declaring a schema, named Pokemon. GraphQL is a strictly typed query language, and user-defined schemas are used to check for the shape of the things the user can ask for as well as what the server should return.
Again, schemas are the what.
Root-level schemas
Root-level schemas are the answer when "How the data would be served?" Is the question.
In GraphQL, the Query schema is considered a top-level or root-level schema, along with Mutation and Subscription. Following the same example, we add two new schemas:
type Query {
allPokemon: [Pokemon]
pokemon(queryBy: QueryPokemonBy): Pokemon
}
input QueryPokemonBy {
id: ID
identifier: String
}
type Query
This is the most important schema of all. This is the one that gets the first hit when GraphQL tries to understand your request. This is the root of all queries and the shape of things that you can ask in your request.
In the example, we have a Query schema with two properties, allPokemon and pokemon. Those properties define how are we going to ask for the data.
Query shows how are we going to ask for some data.
Other types
There are other root type schemas, Mutation and Subscription. Mutations allow us to declare the schema of operators to C*UD in the API, and Subscriptions allow for a live Read operator, that can be updated from the server.
Resolvers
Resolvers are the answer, when "Where the data is coming from?" is the question
Maybe this was the most interesting/difficult thing to understand about GraphQL, but once you get it, it just clicks. This object that the GraphQL needs to understand where the data would come from. It may be tricky, but one thing that would help me to understand is that we are not defining this for request, but for schemas.
const resolvers = {
Query: {
async allPokemon(parent, args, context) {
},
async pokemon(parent, args, context) {
},
},
};
That's the resolver for the Query schema. Each key of the resolvers object represents a defined schema, that holds an object, with properties being functions that would eventually return some data.
But, the wonder about GraphQL is that we don't need to return all the needed data and can even return more data than we are declaring, and that data will be inaccessible. For the data that is missing, it will use resolvers for other schemas to fill them.
Let's review again the primary schema of our app:
type Pokemon {
id: ID!
identifier: String
height: Int
weight: Int
base_experience: Int
order: Int
is_default: Int
image: String
alternativeForms: [Pokemon]
}
Both image and alternativeForms, are not properties that are returned from our database. Instead, the database returns this shape:
Pokemon {
id,
identifier,
species_id,
height,
weight,
base_experience,
order,
is_default,
}
Notice that the database returns the property species_id, and we don't declare it in our shape, yet, we are able to use it inside our app.
This content originally appeared on DEV Community and was authored by Michael De Abreu
Michael De Abreu | Sciencx (2021-02-17T14:39:14+00:00) How to GraphQL? A fair introduction to GraphQL. Retrieved from https://www.scien.cx/2021/02/17/how-to-graphql-a-fair-introduction-to-graphql/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.