Skip to main content

Persisted queries for Django GraphQL

Project description

Pypi Wheel Build Status Codecov Code Climate

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: ()

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-graphql-persist, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size django_graphql_persist-0.1.1-py2.py3-none-any.whl (18.2 kB) File type Wheel Python version 3.6 Upload date Hashes View
Filename, size django-graphql-persist-0.1.1.tar.gz (13.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page