Select Page

How to use GraphQL to drive validated learning through real product — not just code.


Read this article if you are:

  • TL;DR: A tech guy familiarized with Agile (or Lean) methodologies.
  • Developer that suffered from not having tangible results in days (even weeks);
  • Team Leader that wants his team to produce more in less time;
  • Any Software Team that wants to Deliver faster and better.

Personal experience

At WeDevelop, we’ve been implementing the Lean methodology for a few months now. After reading The Lean Startup by Eric Ries, my mind as an entrepreneur and manager changed in big. I started to apply this methodology not only into Product Development processes but into the whole company.

We’ve also been using GraphQL for a long time. It’s our default choice for APIs. It’s powerful at the same time it’s lightweight and flexible.

Surprisingly to me, implementing the Lean methodology (or even iteratively processes) into the daily coding wasn’t that easy. I struggled with concepts of “working smarter, not harder” and “brake it into small versions”.

The problem I found more often was developers spending 1–3 weeks (sometimes more) trying to get to THE solution instead of getting there iteratively.

This is where I used GraphQL to explain by example.


A client asks for a feature, which includes some data visualization and operations over that data. Let’s also consider that we have a decent UI design for this new feature (as the prototyping process is not part of this article).

We have to code it.

Me (acting as Project Manager)“Hi, guys. The client has asked for this feature. I’d like to provide a solution by EOD today. Let’s chat”.

Team: [After discussing specifics] “Ok, but that will take one to two weeks”.

A guy from the team“Hmmm… maybe more…”

Me“I understand but I’d like to provide a solution by EOD today”.

“I’m gonna kill my team leader”

I’ve worked very hard to change the energy of that conversation and my team’s first reaction — By the way, what would be yours?

At first, all my teams were very upset (with me) and negative (with the situation), and misunderstood the meaning of “solution by EOD today”. They worked faster, harder, more hours, …and got frustrated. Sounds familiar?

Now, after many iterations of people getting angry at me, they ask the right question: “Ok, EOD today will mean a “Version 1”, that means not having this and this other thing, and it may be as ugly as hell”.

Now we are talking!

Again, I won’t dig too deep on our Product Development or Delivery Process. If you’d like to know, let me know in the comments and I’ll write about it.

One big delivery

The first move for most developers is to take paper and a pen and start sketching some flowcharts, ERDs, UMLs and other kinds of visualization helpers to come up with the right solution.

It’s my case too. I cannot split up a feature if I don’t have enough clarity. It’s also true that sometimes that clarity doesn’t exist until a few steps later.

The next move (and it was my case for years) is to start to code that solution.

There may be intermediate moves, but the clearest third move is to say “it’s done” and then have the QA department (or worse, customers) saying “no, it’s not done, it fails here and here”. And repeat (it’s like a song, isn’t it?).

Iterative approach

The first move from the previous approach works for me and has worked for teams I’ve worked with. You can’t create something if you don’t know what that is.

The second move I suggest is to think in a “version 1” that can be done as soon as practicable.

How is that?

Forget your complex data structure and smart UMLs that make your world better. Deliver something fast (having in mind your initial design, of course) and then iterate until you get there.

In the end, you will get to that final solution but with a plus: you’ll have validated each iteration and your final solution will be exactly what your customer wants.

How I used GraphQL to explain this

GraphQL is a query language and it also allows us to create very complex data structures to support data visualization and data manipulation.

It’s also where my developers often spent most of their time (starting with long meetings to agree to contracts between backend and frontend with queries, mutations, and complex data types).

So, I came up with a few ideas that made our work simpler:

1. Use simple native Data Types instead of complex structures

Start with the simplest solution possible. It may be not as smart as you’d like but it’ll work and you’ll be able to deliver something quickly. Enums, custom data types, custom scalars, etc, are examples of things that can be simplified in an early version.

2. Mock your resolvers first

There is no need to get from the schema definition to the database design, all at once, to validate your endpoints. You can simply 1) create a very simple version of your schema and then 2) mock your resolvers and deliver working endpoints to your clients (consumers of your endpoints) to do the initial contract validation.

3. Do not introduce breaking changes (use @deprecated)

Introducing breaking changes means that everyone in your team has to iterate the same things at the same time as you do. This is not always possible (and it’s not a good practice either). Instead, keep your GraphQL schema always working. GraphQL provides tools, like the @deprecated directive, to keep your existing schema working and to communicate your teams about breaking changes. In other words, instead of changing a query’s name because you don’t like it (which is fine, naming is very important), add a directive explaining that: @deprecated(message: “I’ll change this query’s name as it’s not meaningful.”); and let your teammates adapt to your new schema as they get there.

4. Don’t be too smart

Us, developers, tend to be too smart. We’re often proud of our smart and complex solutions, even when no one but us can understand them. Just keep it simple, keep it working, keep it easy for commoners to understand. Powerful tools like GraphQL let you do powerful things. Use them to create iterative solutions that make code easy to understand, easy to maintain… just Clean Code.


Creating iterative solutions is an art. An art for developers to iterate as a team, create smart (simple, clean coded) solutions, delivering working software in small chunks. It’s also an art for you to avoid stressing you out trying to create a solution that could take days to be in decent shape to deliver it without partial deliverables.

GraphQL is not magically entangled to the iterative pattern. It’s just a nice and powerful tool, like many others, that can be used to iterate faster and smoother. You can achieve that by using simple data typesmocking your controllersusing directives, and more.

To conclude, I’d like to stress the idea of powerful tools. The more power a tool gives, the more damage it can cause if not used properly. On the other hand, the less powerful a tool is the fewer things to can do with it. Keep it simple, don’t try to be too smart — if you were, there wouldn’t be any need to prove it. Use powerful tools to create cleaner code.

Applying the Lean Methodology gave WeDevelop the ability to deliver working (and simple) software in timelines that sound crazy for most engineers. It also gave us the ability to validate learning and adjust our plan accordingly.

As an individual, it gave me more clarity to solve problems, as I understood that a big problem, no matter how big it is, is just the sum of many smaller ones.