README.rst

Django GraphQL Persist

Persisted queries for Django GraphQL

Dependencies

• Django ≥ 1.11
• Python ≥ 3.4

Installation

Install last stable version from Pypi.

pip install django-graphql-persist

Include the PersistMiddleware middleware in your MIDDLEWARE settings:

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.

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.

GRAPHQL_PERSIST = {
    'DEFAULT_LOADER_ENGINE_CLASS': [
        graphql_persist.loaders.CachedEngine',
    ],
}

Persisted Query definition

You can split schemas into separate files...

documents/fragments.graphql

fragment userFields on UserType {
  id
  email
}

and define Pythonic imports prefixed with #.

documents/GetViewer.graphql

# from fragments import userFields

{
  viewer {
    ...userFields
  }
}

Persisted Query by id

{
  "id": "GetViewer",
  "variables": {}
}

Multiple Operations

documents/users.graphql

# from fragments import userFields

query GetViewer {
  viewer {
    ...userFields
  }
}

query GetUsers($last: Int!) {
  users(last: $last) {
    ...userFields
  }
}

Persisted Query by id and operationName

{
  "id": "users",
  "operationName": "GetUsers",
  "variables": {
    "last": 2
  }
}

✋ Versioning

The versioning scheme is defined by the DEFAULT_VERSIONING_CLASS setting variable.

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

POST /graphql HTTP/1.1
Accept: application/json; version=v1.full

{
  "id": "GetViewer",
  "variables": {}
}

documents/
|
├── v1/
│   ├── full/
│   |     └── GetViewer.graphql 👈
│   └── basic/
|   |     └── GetViewer.graphql
|   └── fragments/
|         └── users.graphql
└── v2/
    └── full/
    └── basic/

👉 documents/v1/full/GetViewer.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: ()