nrel / grapinator

Dynamic GraphQL API Creator for Python

Grapinator Dynamic GraphQL API Creator for Python

Introduction

Grapinator is a dynamic api generator based on the Graphene library for building GraphQL query services. All you have to do to get a fully fuctional GraphQL service up and running is to configure a few setup files!

Key Features

• No coding required: Utilizes Python metaprogramming so no additional coding is required to implement new GraphQL services!
• Built with Flask-SQLAlchemy: Code based on the SQLAlchemy + Flask Tutorial examples.
• Runtime configuration: Runtime configuration is managaged using the grapinator.ini file.
• Flexable GraphQL schema definition: All Graphene and database information is provided by a Python dictionary that you change for your needs. Please review the schema documentation.
• Additional query logic: More robust query logic has been added giving the api consumer more options to query for specific data.

Licensing

This project is licensed under the BSD 3-clause license.

Contributing

Allthough I use this code in production at my company, I consider it alpha code. If you have any ideas, just open an issue and tell me what you think, how it may be improved, bugs you may find, etc.

Getting Started

Demo Prerequisites

• docker
• docker-compose

Docker container setup and Employee database demo setup

• Note: Startup the first time will take a bit longer as the employee database is created on initial load. Look for "Database employeesdb setup complete." in the output of docker-compose before you continue. Once the contaner is started you can start the GraphiQL IDE. See demo_queries.md for some example queries.

# create employee db container
docker/docker_build_grapinatordb

# create grapinator container
docker/docker_build_alpine

# run demo grapinator container. This starts employee db too.
docker-compose -f docker/grapinator.yml up

Development setup

Setup OSX/Linux

python -m venv venv
source venv/bin/activate
(venv) $ export $(cat .env)
(venv) $ pip install -r requirements.txt
(venv) $ python setup.py develop
(venv) $ cd grapinator;python app.py

Setup Windows

python -m venv venv
venv\Scripts\activate.bat
(venv) pip install -r requirements.txt
(venv) python setup.py develop
(venv) set GQLAPI_CRYPT_KEY=[get key from .env]
(venv) cd grapinator
(venv) python app.py

Running unit tests from the command line

Unit tests are located in the 'tests' directory. Integration tests are located in the 'tests_integration' directory.

python -m unittest [filename]

grapinator's Issues

Add graphene.List type for querying using a list [type] in schema

Add the ability to define a list query type within the schema definition. This will define a sqlalchemy synonym for the model to be used in the get_query method.

Example:
{
'gql_col_name': 'actor_id'
,'gql_type': graphene.Int
,'gql_description': 'Actor id (PK).'
,'db_col_name': 'actor_id'
,'db_type': Integer
},
{
'gql_col_name': 'actor_id_list'
,'gql_type': graphene.List
'gql_of_type': 'graphene.Int'
,'gql_description': 'List of Actor id's (PK).'
,'db_col_name': 'actor_id'
,'db_type': 'synonym'
},

Will provide the following for query:

{ actor(actor_id_list: ["1", "2"]) {edges { node { actor_id first_name }}}

Add support for hiding gql fields from output and query

Need to support graphene "exclude_fields" so that gql fields can be hidden from queries and output.

Add more search types to matches clause

Add some more search options to "matches" clause.

Adding the following sqlalchemy orm methods to schema.get_query:
regex, re

regexp_match(value)

From: https://docs.oracle.com/cd/B12037_01/server.101/b10759/ap_posix001.htm

Operator Description
\ a The double backslash character can have four different meanings depending on the context. It can:
• Stand for itself
• Quote the next character
• Introduce an operator
• Do nothing

• Matches zero or more occurrences

• Matches one or more occurrences
  ? Matches zero or one occurrence
  | Alternation operator for specifying alternative matches
  ^ b Matches the beginning-of-line character
  $ b Matches the end-of-line character
  . c Matches any character in the supported character set except NULL
  [ ] d Bracket expression for specifying a matching list that should match any one of the expressions represented in the list. A nonmatching list expression begins with a circumflex (^) and specifies a list that matches any character except for the expressions represented in the list.
  ( ) Grouping expression, treated as a single subexpression
  {m} Matches exactly m times
  {m,} Matches at least m times
  {m,n} Matches at least m times but no more than n times

a '': The backslash operator can be used to make the character following it normal if it is an operator. For example, '*' is interpreted as the asterisk string literal.
b '^' and '$': The characters '^' and '$' are the POSIX anchoring operators. By default, they match only the beginning or end of an entire string. Oracle lets you specify '^' and '$' to match the start or end of any line anywhere within the source string. This in turns lets you treat the source string as multiple lines.
c '.': In the POSIX standard, the "match any character" operator ('.') is defined to match any English character except NULL and the newline character. In the Oracle implementation, the '.' operator can match any character in the database character set, including the newline character.
d '[]': In the POSIX standard, a range in a regular expression includes all collation elements between the start and end points of the range in the linguistic definition of the current locale. Therefore, ranges in regular expressions are linguistic ranges rather than byte values ranges, and the semantics of the range expression are independent of character set. Oracle implements this independence by interpreting range expressions according to the linguistic definition determined by the NLS_SORT initialization parameter.

startswith, sw

ilike(value + '%')

endswith, ew

ilike('%' + value)

One to many joins not working properly

Currently only one primary key may be defined for each table using the schema value DB_TABLE_PK. SQLAlchemy sometimes needs multiple primary keys defined on a database object for proper functionality.

Fix relationship functionality in model.py

Need to update the following code in model.py to allow passing any argument to the SQLAlchemy relationship api.

# TODO: this works for now but needs improvment.
# this sets relationships for table joins in sqlalchemy
for col in clazz_relationships:
    orm_attrs[col['name']] = relationship(
        col['class_name']
        ,primaryjoin=col['arguments']['primaryjoin']
        ,foreign_keys=col['arguments']['foreign_keys']
        ) 

Add support for graphene.List type

List types are used for creating nested results based on relational joins. Need to support adding "of_type" List argument to point to class dynamically generated by grapinator for list results.

Example schema field definition:

        {
            'gql_col_name': 'title'
            ,'gql_of_type': 'grapinator.schema.Title'
            ,'gql_type': graphene.List
            ,'gql_description': 'Employee title'
            ,'db_col_name': 'title'
            ,'db_type': String
        }