Fancy words in Tech Episode II: GraphQL

TLDR: Server and Client Example https://github.com/danielm/graphql-example

What is it, and what's good about It?

It a way for a client to talk to a server in a shared language, usually defined via an schema, to query that server for data, or mutate that data remotely.

The core promise is that schema => or we can call it a contract. Here, Backend and frontend teams should agree on that schema, figure out needs and define what the needs of the application are.

As you can see is a layer, or more like a "wall" between the server and the client (backend/frontend); where it doesn't matter what tech stack is your backend or client are using, they are completely independent; all they share is what they want from each other: the schema (a contract)

Differences with REST

  • Uses a single entry endpoint, that uses a query language to interact with the server.
  • Views the data as a graph structure, where objects are connected by relationships. Different from REST, where you got multiple resources on different endpoints not related to each others.
  • We can specify what data we want back from the server, and what parts of the graph we want to retrieve. Example, from the client we can tell: "hey, we need the title, date and author fields from Posts, and from the Author just the name".
  • Security: trying to do something not specified on the schema --> error
  • Very good on long-living Frontend apps.
  • It's meant to be an all-in-one schema solution, that describes everything a client can do.
  • What a client can or cannot do, shouldn't be based on permissions, we have to assume everything is public (to some extent) and every user can see all possible actions.

Interacting withe the Server

  1. Query: Retrieve data.
  2. Mutation: Alter something on the data: Create/edit/delete/etc..

Schema example

This is what the client and the server must 'agree' on, it has a very simple syntax... very easy to understand just by reading it.

Internally GraphQL has many built in types and we (of course) can define many more.

So lets pretend we want to develop just another ToDo list:

type Task { // Our type
    id: ID!
    content: String!
    completed: Boolean = false
}
type Query {
    tasks: [Task]         // a) Give me all Tasks, (an array of Task)
    task(id: ID!): Task!  // b) Give me one single Taks (by Id) '!' bang means required
}
// a type of payload to recieve when updating a task, note both are optional
input TaskPayload {
    content: String,
    copmleted: Boolean,
}
// c) and our mutation
type mutation {
    update_task(id: ID!, payload: TaskPayload!): Task
}

Here our back-end team will have to implement 3 "resolvers":

  1. resolve_tasks --> returns a collection of Task
  2. resolve_task --> returns a single Task by id
  3. update_task --> a mutation to edit either of the Tasks fields

What is it not? / Cons of GraphQL

  1. It is NOT SQL
  2. Communication between services/microservices of your stack. By design is a way to expose the logic of your backend, to your frontend apps.
  3. Suffers from n+1 problem when retrieving data; backend will have to go and implement solutions for this, like grouping resolvers, caches, etc.. Example: If we request all posts, and on each post we have an 'author' relation, it will generate a Query for each author of each post.
  4. It can be easy to fall into HELL when dealing with advanced relationships, (related to the previous point)

Conclusion

It is great when you want a tight integration between both sides of the APIs, but don't want to both implementations mixed.

Many clients like Apollo implement stuff like caching, subscribe to changes, etc. It becomes some sort of state manager, and with the use of useQuery() for TS/JS makes the usage from the back-end extremely easy.

About
Related Posts
  • Fancy words in Tech Episode III: Design patterns

    This is a immense topic, but on this post I will try to summarize the core concepts and explain the most common design patterns in software (or at least those I've personally run into during my career); like a "cheatsheet", or like a public personal note, that most likely will need to keep updating.

  • Using Makefiles to improve Docker image build experience

    Makefile is a building tool that's been around forever; and while some of us may remember it from building our first couple projects (and may hate those times and the struggle); But I believe it's an awesome tool that by just adding a single file to our project It can speed / easy up our daily work flow on: how we build, run locally, etc our 'Dockerized' projects

  • The SOLID Programming Principles OOP(s)!

    We can think of these as a general guide. There are many more, here are the ones I come up often, they are five and go by the acronym of S.O.L.I.D. The good thing about SOLID is that helps you decouple/breaking apart your code. Giving our modules independence of each other and make our code more maintainable, scalable, reusable and testable.

Comments
The comments are closed on this section.
Hire me!

I'm currently open for new projects or join pretty much any project i may fit in, let me know!

Read about what I do, or contact me for details.