This document discusses the benefits of taking a schema-first approach to building GraphQL APIs compared to a code-first approach. It advocates applying the dependency inversion principle, where the GraphQL schema acts as a contract that clients depend on, rather than implementation details. The Ariadne library is presented as a way to build Python GraphQL servers using SDL and resolve fields with code. While code-first is easier initially, schema-first allows clearer separation of concerns and easier maintenance long-term by prioritizing the client's needs over implementation specifics.

1. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARECOPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Schema-first GraphQL
How I stopped worrying and started to love SDL

2. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Jakub Draganek
Python Developer @ Mirumee Software
Ariadne
Saleor

3. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Background
?

4. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Road to GraphQL
● More flexible API for SPA frontend
● Python & Django Graphene ecosystem
● Saleor API

5. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
import graphene
class House(graphene.ObjectType):
name = graphene.String(required=True)
castle = graphene.String(required=True)
members = graphene.List(graphene.NonNull(lambda: Person))
class Person(graphene.ObjectType):
name = graphene.String(required=True)
house = graphene.Field(House)
parents = graphene.List(graphene.NonNull(lambda: Person))
is_alive = graphene.Boolean()
class Kingdom(graphene.ObjectType):
name = graphene.String(required=True)
castle = graphene.String(required=True)
members = graphene.List(graphene.NonNull(Person))

6. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
class Query(graphene.ObjectType):
kingdoms = graphene.NonNull(
graphene.List(graphene.NonNull(Kingdom)))
def resolve_kingdoms(self, info):
house_of_stark = {"name": "Stark", "castle": "Winterfell"}
king_in_the_north = {
"name": "Jon Snow",
"house": house_of_stark,
"is_alive": True,
}
return [{"name": "The North", "ruler": king_in_the_north}]
schema = graphene.Schema(query=Query)
Code-first!

7. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
type Person {
name: String
house: House
parents: [Person!]
isAlive: Boolean
}
type House {
name: String!
castle: String!
members: [Person!]
}
Result SDL
type Kingdom {
ruler: Person
kings: [Person!]
}
type Query {
kingdoms: [Kingdom!]!
}

8. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
What is the problem?
Code-first is easy and easy is not always good

9. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE

10. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Here be dragons
■ Backend ↔ Frontend collaboration
■ Code reuse
■ CRUD everywhere, hello DB
■ Framework lock-in :(

11. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Back to the drawing board
What is the role of SDL in a GraphQL architecture?

12. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Dependency Inversion Principle

13. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Dependency Inversion Principle
■ High-level modules should not depend on low-level
modules. Both should depend on abstractions.
■ Abstractions should not depend on details. Details
should depend on abstractions.

14. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Dependency Inversion Principle
A B C

15. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Dependency Inversion Principle
A B C

16. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
DIP applied to GraphQL architecture
■ Schema as a contract
■ Client needs before implementation details

17. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Ariadne: bringing schema back

18. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
SDL once again

19. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
type_defs = gql(
"""
type Person {
name: String
house: House
parents: [Person!]
isAlive: Boolean
}
type House {
name: String!
castle: String!
members: [Person!]
}
type Kingdom {
ruler: Person
kings: [Person!]
}
type Query {
kingdoms: [Kingdom!]!
}
"""
)

20. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
query = QueryType()
@query.field("kingdoms")
def resolve_kingdoms(*_):
house_of_stark = {"name": "Stark", "castle": "Winterfell"}
king_in_the_north = {"name": "Jon Snow",
"house": house_of_stark,
"isAlive": True}
return [{"ruler": king_in_the_north}]
schema = make_executable_schema(type_defs, [query])
app = GraphQL(schema)
GraphQL server in Ariadne

21. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Difficult decision

22. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
“We can be blind to the
obvious, and we are also
blind to our blindness.”
Daniel Kahneman

23. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Schema-first benefits
■ Common GraphQL know-how
■ Harder to expose details
■ Easier to maintain
■ Flexible architecture behind the schema
■ QA benefits

24. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
Code-first benefits
■ Potentially less boilerplate
■ Automatic type generation
■ Code and SDL always in sync!
■ Existing solutions for major languages (changing)
■ Great for simple data access

25. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
More in the article on our blog

26. COPYRIGHT © 2009–2019 MIRUMEE SOFTWARE
THANK YOU!
QUESTIONS?