Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/leam-tech/frappe_graphql
GraphQL API Layer for Frappe Framework
https://github.com/leam-tech/frappe_graphql
erpnext frappe graphql
Last synced: 6 days ago
JSON representation
GraphQL API Layer for Frappe Framework
- Host: GitHub
- URL: https://github.com/leam-tech/frappe_graphql
- Owner: leam-tech
- License: other
- Created: 2021-02-02T03:19:05.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-02-07T12:29:04.000Z (almost 2 years ago)
- Last Synced: 2024-09-02T08:05:30.446Z (4 months ago)
- Topics: erpnext, frappe, graphql
- Language: Python
- Homepage:
- Size: 249 KB
- Stars: 43
- Watchers: 8
- Forks: 26
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: license.txt
Awesome Lists containing this project
- awesome-frappe - Frappe GraphQL - GraphQL API Layer for Frappe Framework. (Uncategorized / Uncategorized)
README
## Frappe Graphql
GraphQL API Layer for Frappe Framework
#### License
MIT
## Instructions
Generate the sdls first
```
$ bench --site test_site graphql generate_sdl
```
and start making your graphql requests against:
```
/api/method/graphql
```
# Features
## Getting single Document and getting a filtered doctype list
You can get a single document by its name using `` query.
For sort by fields, only those fields that are search_indexed / unique can be used. NAME, CREATION & MODIFIED can also be used
Example
Query
```
{
User(name: "Administrator") {
name,
email
}
}
```
You can get a list of documents by querying ``. You can also pass in filters and sorting details as arguments:
```graphql
{
Users(filter: [["name", "like", "%a%"]], sortBy: { field: NAME, direction: ASC }) {
totalCount,
pageInfo {
hasNextPage,
hasPreviousPage,
startCursor,
endCursor
},
edges {
cursor,
node {
name,
first_name
}
}
}
}
}
```
## Access Field Linked Documents in nested queries
All Link fields return respective doc. Add `__name` suffix to the link field name to get the link name.
Example
Query
```gql
{
ToDo (limit_page_length: 1) {
name,
priority,
description,
assigned_by__name,
assigned_by {
full_name,
roles {
role__name,
role {
name,
creation
}
}
}
}
}
```
Result
```json
{
"data": {
"ToDo": [
{
"name": "ae6f39845b",
"priority": "Low",
"description": "
Do this
",
"assigned_by__name": "Administrator",
"assigned_by": {
"full_name": "Administrator",
"roles": [
{
"role__name": "System Manager",
"role": {
"name": "System Manager",
"creation": "2021-02-02 08:34:42.170306",
}
}
]
}
}
...
]
}
}
```
## Restrict Query/Mutation depth
Query/Mutation is restricted by default to 10.
You can change the depth limit by setting the site config `frappe_graphql_depth_limit: 15`.
## Subscriptions
Get notified instantly of the updates via existing frappe's SocketIO. Please read more on the implementation details [here](./docs/subscriptions.md)
## File Uploads
File uploads can be done following the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec). `uploadFile` mutation is included implementing the same
Example
Query
```http
POST /api/method/graphql HTTP/1.1
Host: test_site:8000
Accept: application/json
Cookie: full_name=Administrator; sid=; system_user=yes; user_id=Administrator; user_image=
Content-Length: 553
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="operations"
{
"query": "mutation uploadFile($file: Upload!) { uploadFile(file: $file) { name, file_url } }",
"variables": {
"file": null
}
}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="map"
{ "0": ["variables.file"] }
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="0"; filename="/D:/faztp12/Pictures/BingImageOfTheDay_20190715.jpg"
Content-Type: image/jpeg
(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW
```
Response
```json
{
"data": {
"uploadFile": {
"name": "ce36b2e222",
"file_url": "/files/BingImageOfTheDay_20190715.jpg"
}
}
}
```
## RolePermission integration
Data is returned based on Read access to the resource
## Standard Mutations: set_value , save_doc & delete_doc
- [SET_VALUE Mutation](./docs/SET_VALUE.md)
- [SAVE_DOC Mutation](./docs/SAVE_DOC.md)
- [DELETE_DOC Mutation](./docs/DELETE_DOC.md)
## Pagination
Cursor based pagination is implemented. You can read more about it here: [Cursor Based Pagination](./docs/cursor_pagination.md)
## Support Extensions via Hooks
You can extend the SDLs with additional query / mutations / subscriptions. Examples are provided for a specific set of Scenarios. Please read [GraphQL Spec](http://spec.graphql.org/June2018/#sec-Object-Extensions) regarding Extending types. There are mainly two hooks introduced:
- `graphql_sdl_dir`
Specify a list of directories containing `.graphql` files relative to the app's root directory.
eg:
```py
# hooks.py
graphql_sdl_dir = [
"./your-app/your-app/generated/sdl/dir1",
"./your-app/your-app/generated/sdl/dir2",
]
```
The above will look for graphql files in `your-bench/apps/your-app/your-app/generated/sdl/dir1` & `./dir2` folders.
- `graphql_schema_processors`
You can pass in a list of cmd that gets executed on schema creation. You are given `GraphQLSchema` object (please refer [graphql-core](https://github.com/graphql-python/graphql-core)) as the only parameter. You can modify it or extend it as per your requirements.
This is a good place to attach the resolvers for the custom SDLs defined via `graphql_sdl_dir`
## Support Extension of Middlewares via hooks
We can add graphql middlewares by adding the path through hooks.
Please note the return type and arguments being passed to your custom middleware.
```py
# hooks.py
graphql_middlewares = ["frappe_graphql.utils.middlewares.disable_introspection_queries.disable_introspection_queries"]
```
```py
def disable_introspection_queries(next_resolver, obj, info: GraphQLResolveInfo, **kwargs):
# https://github.com/jstacoder/graphene-disable-introspection-middleware
if is_introspection_disabled() and info.field_name.lower() in ['__schema', '__introspection']:
raise IntrospectionDisabled(frappe._("Introspection is disabled"))
return next_resolver(obj, info, **kwargs)
def is_introspection_disabled():
return not cint(frappe.local.conf.get("developer_mode")) and \
not cint(frappe.local.conf.get("enable_introspection_in_production"))
```
## Introspection in Production
Introspection is disabled by default in production mode. You can enable by setting the site config `enable_introspection_in_production: 1`.
## Helper wrappers
- Exception Handling in Resolvers. We provide a utility resolver wrapper function which could be used to return your expected exceptions as user errors. You can read more about it [here](./docs/resolvers_and_exceptions.md).
- Role Permissions for Resolver. We provide another utility resolver wrapper function which could be used to verify the logged in User has the roles specified. You can read more about it [here](./docs/resolver_role_permissions.md)
## Examples
### Adding a newly created DocType
- Generate the SDLs in your app directory
```bash
# Generate sdls for all doctypes in
$ bench --site test_site graphql generate_sdl --output-dir --app
# Generate sdls for all doctype in module
$ bench --site test_site graphql generate_sdl --output-dir --module -m -m
# Generate sdls for doctype <2>
$ bench --site test_site graphql generate_sdl --output-dir --doctype -dt -dt
# Generate sdls for all doctypes in without Enums for Select Fields
$ bench --site test_site graphql generate_sdl --output-dir --app --disable-enum-select-fields
```
- Specify this directory in `graphql_sdl_dir` hook and you are done.
### Introducing a Custom Field to GraphQL
- Add the `Custom Field` in frappe
- Add the following to a `.graphql` file in your app and specify its directory via `graphql_sdl_dir`
```graphql
extend type User {
is_super: Int!
}
```
### Adding a Hello World Query
- Add a cmd in `graphql_schema_processors` hook
- Use the following function definition for the cmd specified:
```py
def hello_world(schema: GraphQLSchema):
def hello_resolver(obj, info: GraphQLResolveInfo, **kwargs):
return f"Hello {kwargs.get('name')}!"
schema.query_type.fields["hello"] = GraphQLField(
GraphQLString,
resolve=hello_resolver,
args={
"name": GraphQLArgument(
type_=GraphQLString,
default_value="World"
)
}
)
```
- Now, you can query like query like this:
```py
# Request
query Hello($var_name: String) {
hello(name: $var_name)
}
# Variables
{
"var_name": "Mars"
}
# Response
{
"data": {
"hello": "Hello Mars!"
}
}
```
### Adding a DocMeta Query
```py
# Add the cmd to the following function in `graphql_schema_processors`
def docmeta_query(schema):
from graphql import GraphQLField, GraphQLObjectType, GraphQLString, GraphQLInt
schema.query_type.fields["docmeta"] = GraphQLField(
GraphQLList(GraphQLObjectType(
name="DocTypeMeta",
fields={
"name": GraphQLField(
GraphQLString,
resolve=lambda obj, info: obj
),
"number_of_docs": GraphQLField(
GraphQLInt,
resolve=lambda obj, info: frappe.db.count(obj)
),
}
)),
resolve=lambda obj, info: [x.name for x in frappe.get_all("DocType")]
)
```
Please refer `graphql-core` for more examples
### Adding a new Mutation
There are two ways:
1. Write SDL and Attach Resolver to the Schema
```graphql
# SDL for Mutation
type MY_MUTATION_OUTPUT_TYPE {
success: Boolean
}
extend type Mutation {
myNewMutation(args): MY_MUTATION_OUTPUT_TYPE
}
```
```py
# Attach Resolver (Specify the cmd to this function in `graphql_schema_processors` hook)
def myMutationResolver(schema: GraphQLSchema):
def _myMutationResolver(obj: Any, info: GraphQLResolveInfo):
# frappe.set_value(..)
return {
"success": True
}
mutation_type = schema.mutation_type
mutation_type.fields["myNewMutation"].resolve = _myMutationResolver
```
2. Make use of `graphql-core` apis
```py
# Specify the cmd to this function in `graphql_schema_processors` hook
def bindMyNewMutation(schema):
def _myMutationResolver(obj: Any, info: GraphQLResolveInfo):
# frappe.set_value(..)
return {
"success": True
}
mutation_type = schema.mutation_type
mutation_type.fields["myNewMutation"] = GraphQLField(
GraphQLObjectType(
name="MY_MUTATION_OUTPUT_TYPE",
fields={
"success": GraphQLField(
GraphQLBoolean,
resolve=lambda obj, info: obj["success"]
)
}
),
resolve=_myMutationResolver
)
```
### Modify the Schema randomly
```py
def schema_processor(schema: GraphQLSchema):
schema.query_type.fields["hello"] = GraphQLField(
GraphQLString, resolve=lambda obj, info: "World!")
```