https://github.com/flavors/django-graphql-persist
Persisted queries for Graphene Django
https://github.com/flavors/django-graphql-persist
cache django graphene graphql persist persisted versioning
Last synced: 6 months ago
JSON representation
Persisted queries for Graphene Django
- Host: GitHub
- URL: https://github.com/flavors/django-graphql-persist
- Owner: flavors
- License: mit
- Created: 2018-04-04T14:02:49.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-02-09T21:15:13.000Z (over 6 years ago)
- Last Synced: 2025-03-25T06:21:43.225Z (6 months ago)
- Topics: cache, django, graphene, graphql, persist, persisted, versioning
- Language: Python
- Homepage: https://pypi.python.org/pypi/django-graphql-persist
- Size: 66.4 KB
- Stars: 24
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.rst
- License: LICENSE
Awesome Lists containing this project
README
Django GraphQL Persist
======================
|Pypi| |Wheel| |Build Status| |Codecov| |Code Climate|
**Persisted queries** for `Django GraphQL`_
.. _Django GraphQL: https://github.com/graphql-python/graphene-django
Dependencies
------------
* Django ≥ 1.11
* Python ≥ 3.4
Installation
------------
Install last stable version from Pypi.
.. code:: sh
pip install django-graphql-persist
Include the ``PersistMiddleware`` middleware in your *MIDDLEWARE* settings:
.. code:: python
MIDDLEWARE = [
...
'graphql_persist.middleware.PersistMiddleware',
...
]
Loaders
-------
*Django-graphql-persist* searches for documents directories in a number of places, depending on your ``DEFAULT_LOADER_CLASSES`` variable.
By default, *Django-graphql-persist* uses these document loaders:
* **AppDirectoriesLoader**
Loads documents from Django apps on the filesystem. For each app in ``INSTALLED_APPS``, the loader looks for a ``documents/`` subdirectory defined by ``APP_DOCUMENT_DIR`` variable.
* **FilesystemLoader**
Loads documents from the filesystem, according to ``DOCUMENTS_DIRS`` variable.
* **URLLoader**
Loads documents from urls, according to ``DOCUMENTS_DIRS``.
.. code:: python
GRAPHQL_PERSIST = {
'DOCUMENTS_DIRS': [
'/app/documents', # FilesystemLoader
'https:// ... /documents', # URLLoader
],
}
**Cached Loader**
By default, the document system reads your documents every time they're rendered.
Configure the ``CachedEngine`` engine for caching documents.
.. code:: python
GRAPHQL_PERSIST = {
'DEFAULT_LOADER_ENGINE_CLASS': [
graphql_persist.loaders.CachedEngine',
],
}
Persisted Query definition
--------------------------
You can split schemas into separate files...
``documents/fragments.graphql``
.. code:: graphql
fragment userFields on UserType {
id
email
}
and define Pythonic imports prefixed with ``#``.
``documents/GetViewer.graphql``
.. code:: graphql
# from fragments import userFields
{
viewer {
...userFields
}
}
**Persisted Query by** ``id``
.. code:: json
{
"id": "GetViewer",
"variables": {}
}
Multiple Operations
-------------------
``documents/users.graphql``
.. code:: graphql
# from fragments import userFields
query GetViewer {
viewer {
...userFields
}
}
query GetUsers($last: Int!) {
users(last: $last) {
...userFields
}
}
**Persisted Query by** ``id`` and ``operationName``
.. code:: json
{
"id": "users",
"operationName": "GetUsers",
"variables": {
"last": 2
}
}
✋ Versioning
-------------
The versioning scheme is defined by the ``DEFAULT_VERSIONING_CLASS`` setting variable.
.. code:: python
GRAPHQL_PERSIST = {
'DEFAULT_VERSIONING_CLASS': 'graphql_persist.versioning.AcceptHeaderVersioning'
}
This is the full **list of versioning classes**.
+--------------------------+-------------------------------------+
| DEFAULT_VERSIONING_CLASS | Example |
+==========================+=====================================+
| AcceptHeaderVersioning | ``application/json; version=v1`` |
+--------------------------+-------------------------------------+
| VendorTreeVersioning | ``application/vnd.example.v1+json`` |
+--------------------------+-------------------------------------+
| QueryParameterVersioning | ``?version=v1`` |
+--------------------------+-------------------------------------+
| HostNameVersioning | ``v1.example.com`` |
+--------------------------+-------------------------------------+
Configure the versioning scheme and storage the GraphQL documents according to the version.
👇 **Example**
.. code::
POST /graphql HTTP/1.1
Accept: application/json; version=v1.full
{
"id": "GetViewer",
"variables": {}
}
.. code::
documents/
|
├── v1/
│ ├── full/
│ | └── GetViewer.graphql 👈
│ └── basic/
| | └── GetViewer.graphql
| └── fragments/
| └── users.graphql
└── v2/
└── full/
└── basic/
👉 ``documents/v1/full/GetViewer.graphql``
.. code:: graphql
# from ..fragments.users import userFields
{
viewer {
...userFields
}
}
Settings
--------
Here's a **list of settings** available in *Django-graphql-persist* and their default values.
**DOCUMENTS_DIRS**
::
List of directories or urls searched for GraphQL SDL definitions
Default: ()
**CACHE_NAME**
::
Cache key name `CACHES[name]` to cache the queries results
Default: 'default'
**QUERY_KEY_HANDLER**
::
A custom function `f(query_id, request)` to generate the persisted query keys
Default: 'graphql_persist.query.query_key_handler'
**DEFAULT_VERSIONING_CLASS**
::
A versioning class to determine the `request.version` attribute
Default: None
**DEFAULT_LOADER_ENGINE_CLASS**
::
Class that takes a list of template loaders and attempts to load templates from them in order
Default: 'graphql_persist.loaders.Engine'
Note: Set variable to 'graphql_persist.loaders.CachedEngine' for caching documents
**DEFAULT_LOADER_CLASSES**
::
A list of loader classes to import documents from a particular source
Default: (
'graphql_persist.loaders.AppDirectoriesLoader',
'graphql_persist.loaders.FilesystemLoader',
'graphql_persist.loaders.URLLoader',
)
**APP_DOCUMENT_DIR**
::
Subdirectory of installed applications for searches documents
Default: 'documents'
**DOCUMENTS_EXT**
::
GraphQL document file extension
Default: '.graphql'
**DEFAULT_RENDERER_CLASSES**
::
A list of renderer classes that may be used when returning a persisted query response
Default: ()
.. |Pypi| image:: https://img.shields.io/pypi/v/django-graphql-persist.svg
:target: https://pypi.python.org/pypi/django-graphql-persist
.. |Wheel| image:: https://img.shields.io/pypi/wheel/django-graphql-persist.svg
:target: https://pypi.python.org/pypi/django-graphql-persist
.. |Build Status| image:: https://travis-ci.org/flavors/django-graphql-persist.svg?branch=master
:target: https://travis-ci.org/flavors/django-graphql-persist
.. |Codecov| image:: https://img.shields.io/codecov/c/github/flavors/django-graphql-persist.svg
:target: https://codecov.io/gh/flavors/django-graphql-persist
.. |Code Climate| image:: https://api.codeclimate.com/v1/badges/46eaf45a95441d5470a4/maintainability
:target: https://codeclimate.com/github/flavors/django-graphql-persist