Real World Graphene

Graphene is currently the most popular framework for building a GraphQL in Python and it’s also an obvious choice for adding a GraphQL layer to Django applications. Over the course of a year, we successfully built an API with about 50 queries and over 100 mutations on top of existing Django project (Saleor), but we also learned some hard lessons and had to overcome several shortcomings of the framework along the way.

In this talk, I’d like to share some practical tips to overcome the most common problems that a Django developer might face when building an optimized and maintainable API with Graphene, such as: - using useful abstractions to build queries and mutations faster - optimizing database queries in a graph - structuring a large Graphene project - unified error handling

I’d also like to bring up a few limitations of the framework that we discovered as we were working on the project and then end the talk with the most important benefits that adoption of GraphQL brings to modern web applications development - both for the backend and frontend.

Transcript

1. PyCon Korea 2019 Real World Graphene Lessons learned from building a GraphQL API on top of a large Django project @maarcingebala
2. ▪ Python developer at Mirumee Software & development lead at Saleor ▪ Building and maintaining a GraphQL API for the last two years ▪ Managing the open-source community at Saleor Who I am
3. ▪ Basic concepts of GraphQL & Graphene ▪ Saleor - our journey with GraphQL ▪ Graphene: lessons learned ▪ Problems & limitations Agenda
4. GraphQL Basic Concepts
5. ▪ GraphQL is a data query language ▪ Developed by Facebook in 2012, open-sourced in 2015, managed by Linux Foundation since 2018. ▪ Alternative to REST ▪ Goals: ◦ minimize amounts of data transferred (data overfetching / underfetching) ◦ increase developer productivity ▪ In 2019, GraphQL is a megatrend. A bit of history
6. Companies using GraphQL Source: Geoff Schmidt’s talk from GraphQL Summit 2018 (https://youtu.be/IjJkAL4RWyQ)
7. Fun fact
10. Queries - fetching data Mutations - modifying data on the server Subscriptions - real-time data exchange over websockets ▪ Client decides what data to return from the server. ▪ All operations are sent as POST requests. ▪ There is only one API endpoint: /graphql. Operations
11. Schema Definition Language Schema is a strongly typed contract between backend and frontend. It decouples client’s logic from server’s logic by defining data structures and operations available in API. Type definitions Operation definitions
12. Queries allow fetching data from the server. Queries Fetching data by the client
13. JSON response from the server - only requested fields Queries allow fetching data from the server. Fetching data by the client Queries
14. Mutations allow modification of data on the server. Mutations Mutation to update a customer
15. Mutations allow modification of data on the server. Server response Mutation to update a customer Mutations
16. Graphene
17. ▪ Building schema using Python classes (code-first approach) ▪ Support for various web frameworks (Django, Flask, Tornado) ▪ Almost 5000 stars on Github Graphene https://graphene-python.org https://github.com/graphql-python
18. Graphene Django A type created from a Django model
19. Graphene Django A type created from a Django model Query to fetch all users from the database
20. Saleor
21. Saleor - GraphQL-first headless e-commerce github.com/mirumee/saleor
22. ▪ 50 queries and 200 mutations ▪ Authentication & permissions ▪ Filtering, sorting, search Saleor GraphQL API - summary Public demo: demo.getsaleor.com/graphql
23. Graphene: Lessons Learned
24. Lesson 1 Project Structure
25. ▪ types.py - definitions of Graphene types, mapping models to types ▪ resolvers.py - resolver functions for queries ▪ mutations.py - definitions of mutation classes ▪ schema.py - gathers all types, queries, and mutations and exposes the part of schema specific for this module Project structure
26. Lesson 2 Authentication & Permissions
27. Using JSON Web Tokens to authenticate users with django-graphql-jwt. Use HTTP Authorization header to pass the token in subsequent requests and authorize them. Authentication
28. Use HTTP Authorization header to pass the token in subsequent requests and authorize them. Authentication Mutation to generate a new token Using JSON Web Tokens to authenticate users with django-graphql-jwt.
29. Mutation to generate a new token Response with the token and user data Use HTTP Authorization header to pass the token in subsequent requests and authorize them. Authentication Using JSON Web Tokens to authenticate users with django-graphql-jwt.
30. Permissions Restricting access to queries and mutations with django-graphql-jwt.
31. Permissions Restricting access to queries and mutations with django-graphql-jwt.
32. Lesson 3 Unified Mutations
33. The default implementation of mutations in Graphene has some limitations: ▪ no input data validation ▪ no standard for returning errors ▪ a lot of boilerplate in large APIs Mutations in Graphene
34. Unified error handling
35. Unified error handling All mutations return the same “errors” structure.
36. Unified error handling All mutations return the same “errors” structure. Try to perform the mutation logic and return success response.
37. Unified error handling All mutations return the same “errors” structure. Try to perform the mutation logic and return success response. Catch all validation errors and convert them to a Graphene type.
38. Mutations to create new model instances follow the same logic. Unified mutations CLEAN INPUT DATA CREATE MODEL INSTANCE VALIDATE SAVE INSTANCE
39. Unified mutations Mutations to create new model instances follow the same logic. CLEAN INPUT DATA CREATE MODEL INSTANCE VALIDATE SAVE INSTANCE
40. Unified mutations Mutations to create new model instances follow the same logic. CLEAN INPUT DATA CREATE MODEL INSTANCE VALIDATE SAVE INSTANCE Example model mutation
41. Lesson 4 Database Queries Optimization
42. Client can ask for any combination of fields exposed in a type, but some of them are relations in the database. This may result in duplicated database queries. N+1 problem PRODUCT IMAGE * 1
43. Client can ask for any combination of fields exposed in a type, but some of them are relations in the database. This may result in duplicated database queries. N+1 problem PRODUCT IMAGE * 1
44. Client can ask for any combination of fields exposed in a type, but some of them are relations in the database. This may result in duplicated database queries. ▪ products(first:1) - 2 database hits ▪ products(first:20) - 21 database hits N+1 problem PRODUCT IMAGE * 1
45. Dynamically join database tables based on fields in a query with decorators provided by graphene-django-optimizer. Database optimization https://docs.djangoproject.com/en/2.2/ ref/models/querysets/#select-related Uses Django’s select_related and prefetch_related methods.
46. Problems and Limitations
47. ▪ A fully-fledged API requires multiple additional third-party libraries on top of Graphene. ▪ No way to serve multiple schemas e.g. private and public API. ▪ Lack of good resources, inconsistent docs. ▪ Non-pythonic concepts in the source code. Problems and limitations
48. Summary
49. ▪ GraphQL is a great tool for data exchange between backend and frontend and many companies are already using it. ▪ Headless architecture decouples backend and frontend and allows us to efficiently integrate our apps with other services. ▪ Graphene is the most popular code-first GraphQL framework for Python that allows for building powerful APIs. ▪ Graphene needs more support from the community. ▪ GraphQL ecosystem in Python is growing. Summary
50. Ariadne is a Python library for implementing schema-first GraphQL servers that is simple to use and open for extension. ▪ Schema-first approach ▪ Support for asynchronous execution ▪ Inspired by Apollo Server Read more about schema-first vs. code-first approaches in our article “Schema-first: The Road Less Travelled”. ariadnegraphql.org Ariadne
51. ▪ github.com/graphql-python - Graphene ecosystem ▪ flavors/django-graphql-jwt - JWT authentication & permissions ▪ tfoxy/graphene-django-optimizer - database optimization ▪ lmcgartland/graphene-file-upload - file upload ▪ mirumee/ariadne - schema-first GraphQL server ▪ dailymotion/tartiflette - asyncio-based GraphQL server ▪ strawberry-graphql/strawberry - GraphQL library based on dataclasses ▪ mirumee/saleor - Saleor repository, example of a large Graphene project Resources
52. Thank you 고맙습니다 @maarcingebala