Adding GraphQL to DjangoCMS allows exposing data through an api in a structured way. This can be used to build a cms frontend in other technologies or integrate a cms with more applications.
Installing packages
Install package ‘graphene-django’ from pip. This will also install:
- graphene
- graphql-core
- graphql-relay
Package graphene enables main functionality of graphql and graphene-django allows using django models as nodes in graphql.
Configuration
In the settings.py add ‘graphene_django’ to INSTALLED_APPS and add configuration for graphene:
where SCHEMA points to a file that will contain schema definitions.
Inside urls.py add
and to ‘urlpatterns`
Where option `graphiql` will enable an interactive console in the web browser.
Adding a schema
Next step is to define a schema. Create a file schema.py and import DjangoObjectType.
Create a class Query that will hold all of graphql queries:
Add Query class to schema:
The schema variable is the one that is pointed to in the settings file.
Next step is to create an object that can be returned by query. For django models you have to inherit from DjangoObjectType. Class names in graphql usually end with Type on Node. Inside Meta class configure what django model will use. If a model uses parler for translation of fields then for every translated field you have to manually define a type and source for graphene fields.
Inside Query class add two new queries
First one is for returning collections of people and the second one for returning a single object by its ID.
Next step is to add a function that can populate return types with data. For that you have to add a `resolve_*` function inside a Query class. Because the person class defines a Node interface, therefore all object ids will be encoded with base64 in the form `model:ID`. To get id back use `from_global_id` function.
Go to `localhost/graphql` interactive console and run:
`getPeope` is a convenient query name that doesn’t matter. `people` is the actual query defined in the Query class, and `id`, `name`, `email` are fields in the django model that will be returned.
To query for specific person use:
Where ID can be obtained from people's query.
To add “searching” and “pagination” to people query add two new input parameters for query:
and inside a resolver function, use these parameters to modify a QuerySet to return only interesting entities. This will enable searching inside an email field and returning only X first matches.
Go to `localhost/graphql` interactive console and run:
to search for everyone with email containing string michal, or
to get the first 5 email addresses.
To add a mutation that can modify an object create a new class:
where Meta defines which django model to use, Arguments class defines a list of arguments that will be used in mutation query and a mutate method that takes arguments, updates a model and returns a mutation class.
Create a new mutations class:
and add it to schema:
Conclusion
Graphene is a great library that can help expose endpoints with a relatively little configuration. Adding new endpoints is simple when you get a grasp of graphene code conventions. This allows rapid development of APIs that expose data in logical and easy to follow ways.
