{"id":15280,"date":"2021-05-26T16:54:21","date_gmt":"2021-05-26T20:54:21","guid":{"rendered":"https:\/\/qxf2.com\/blog\/?p=15280"},"modified":"2021-06-14T06:49:58","modified_gmt":"2021-06-14T10:49:58","slug":"graphql-flask-jwt-sqlalchemy","status":"publish","type":"post","link":"https:\/\/qxf2.com\/blog\/graphql-flask-jwt-sqlalchemy\/","title":{"rendered":"Flask app with a GraphQL API, JWT Authentication and SQLAlchemy"},"content":{"rendered":"

I wrote (and open sourced) a Flask app with a GraphQL API<\/a> that was implemented using Graphene<\/a>. The application is similar to the official Graphene example<\/a> but includes the following:<\/p>\n

1. JWT authentication
\n2. An example of filtering
\n3. A minimal amount of data for people to tinker with the app<\/p>\n

This article is suitable for:
\na) Testers looking to get started with writing GraphQL queries, using GraphiQL and the mod-header plugin and (optionally) Python
\nb) Developers looking for an example of a Flask app that implements a GraphQL API along with authentication<\/p>\n

Note to developers<\/b>: I am not a developer! Treat the code I have shared as a beginner-level introduction to Flask + Graphene + GraphQL filtering + SQLAlchemy + JWT authentication. The only reason I am sharing my application code is because I did not find a full working example online that showed authentication, filtering along with the data for a Flask application.<\/p>\n

\n

Outline of the post<\/h3>\n

We will be covering the following steps in this post. Developers can stop at the end of step 1. QA folks can play along through the end. As you read through this post, commands<\/span> and filenames<\/span> will be in blue<\/span>.<\/p>\n

1. Environment setup<\/a>
\n  1a. Get code and install dependencies
\n  1b. Setup the data
\n  1c. Add credentials
\n  1d. Start the application<\/p>\n

2. GraphQL query using GraphiQL<\/a>
\n  2a. Install ModHeader plugin
\n  2b. Authentication
\n  2c. Query all employees
\n  2d. Query based on a field<\/p>\n

3. GraphQL query using Python<\/a><\/p>\n

\n

1. Environment setup<\/a><\/h3>\n

This section will let you run the Flask app with a simple GraphQL API. The instructions here are explicit to help beginners. I assume you have git setup along with Python 3.7 (or higher) and virtualenv<\/a>.<\/p>\n

1a. Get code and install dependencies<\/h4>\n

i. Clone the repo using the command: git clone https:\/\/github.com\/qxf2\/qxf2-employees.git<\/span>.
\nii. Once you have cloned the repo cd qxf2-employees\/<\/span> to get into the root directory of the repository.
\niii. Next, create a virtual environment for this project with the command virtualenv -p python3.8 venv-employee-database<\/span>.
\niv. Activate your virtual environment source venv-employee-database\/Scripts\/activate<\/span> (Windows) or source venv-employee-database\/bin\/activate<\/span> (*nix).
\nv. Install the dependencies using the command pip install -r requirements.txt<\/span>. <\/p>\n

At this stage, you have gotten the code and setup the dependencies.<\/p>\n

1b. Setup the data<\/h4>\n

I have shipped some data with the repository. Let us set it up in a SQLite<\/a> database. To do that, create a new database using the command sqlite3 data\/employee_database.sqlite3<\/span>. This will give you a sqlite prompt. In that prompt, enter the following commands<\/p>\n

i. Get ready to import csv: .mode csv<\/span>
\nii. Import the data: .import data\/dummy_data.csv employee<\/span>
\niii. Verify the data was imported right: select * from employee;<\/span> … this step should show you two rows.
\niv. Quit .quit<\/span><\/p>\n

Carefully observe the output of step iii above. It will show you that the data has two rows and several columns. We will be querying this data via the GraphQL API.<\/p>\n

Now, you should have a data\/employee_database.sqlite3<\/code> file present with some data in it. The hardest parts of the setup are over. <\/p>\n

1c. Add credentials<\/h4>\n

Let us add a couple of credentials. One for the app secret. Another to setup a user to query the GraphQL API.<\/p>\n

i. Update the file employees\/secret.py<\/span> with any secret string you want to use.
\nii. Next, create a file called employees\/allowed_users.py<\/span>
\niii. Add one line to the file created in step ii (a Python dictionary) USERS = {“user1”: “password1”}<\/span>.<\/p>\n

1d. Start the application<\/h4>\n

Now, you are ready to start the application.<\/p>\n

i. Run the command python run.py<\/span>.
\nii. You should see a console message letting you know that the application has started on localhost:5000.
\niii. To verify, launch your browser and visit http:\/\/localhost:5000\/graphql<\/span>.
\niv. If all goes well, you should see the GraphiQL editor.<\/p>\n

\"graphiql<\/p>\n

\n

2. GraphQL queries using GraphiQL<\/a><\/h3>\n

The tool you saw at the end of the setup (on \/graphql) is called GraphiQL (pronounced graphical). It is a web interface that lets you query the GraphQL API. You can think of it as the equivalent of a primitive Postman for GraphQL APIs. <\/p>\n

Note 1:<\/b> Hey, testers – your developers will give you the API being exposed and the fields that can be queried. So as you go through these examples, do not worry if you do not know where some of the syntax comes from. <\/p>\n

Note 2:<\/b> For the really curious ones, the fields exposed comes from employees\/model.py and the query names come from employees\/schema.py. For both, you will need to get rid of the underscore and use camel case. E.g.: github_id becomes githubId. <\/p>\n

2a. Install ModHeader plugin<\/h4>\n

Our application uses JWT authentication and the token is passed via the header. So before we dive into writing queries, let us add a browser plugin that lets us modify the header. I chose the ModHeader<\/a> extension.<\/p>\n

2b. Authentication<\/h4>\n

Once you have the ModHeader plugin, first authenticate with the server and receive a token. To do that, in your GraphiQL editor, paste the following:<\/p>\n

\r\nmutation {\r\n    auth(username: \"user1\", password: \"password1\") {\r\n        accessToken\r\n        refreshToken\r\n        }\r\n}\r\n<\/pre>\n
This should return an access token as well as a refresh token. Your GraphiQL editor should look like the screenshot below.<\/p>\n
\"GraphiQL<\/p>\n
Copy the access token. Open your ModHeader extension, add a Authorization<\/span> header and paste the strong Bearer access_token<\/span> as the value where access_token<\/span> is the value of your access token. Your ModHeader plugin should look something like the screenshot below:<\/p>\n
\"ModHeader<\/p>\n
Now you are set to make queries. Our application exposes just two queries. One to query all employees. Another to query employees based on a given email or Skype id.<\/p>\n
2c. Query for all employees<\/h4>\n
Let us query for all employees and get their email, id, join date, if they are active and their author name fields. To query all employees, use the following snippet in your GraphiQL editor<\/p>\n
\r\nquery findAllEmployees{\r\n    allEmployees{\r\n        edges{\r\n            node{\r\n                email\r\n                employeeId\r\n                dateJoined\r\n                isActive\r\n                blogAuthorName\r\n            }\r\n        }\r\n    }\r\n}\r\n<\/pre>\n
One way to understand this query is that allEmployees<\/span> is the query exposed by the GraphQL API and will usually be given to you by the developer. You are creating a named query called findAllEmployees (you can use any name here) and then within it, calling allEmployees<\/span>. You want only some properties of the employee node. To do that you add a node<\/span> element and list the properties of employees that you want – email, employee id, join date, etc.<\/p>\n
If you have setup ModHeader correctly, you should see an output similar to the screenshot below:<\/p>\n
\"GraphQL<\/p>\n
2d. Query based on a field<\/h4>\n
Finally, let us filter the employees table based on email and find that employee’s Skype id and GitHub id. To do that, execute the following snippet:<\/p>\n
\r\nquery FindEmployeeByEmail($email: String = \"lasker@qxf2.com\") {\r\n    findEmployee(email: $email) {\r\n        githubId\r\n        skypeId\r\n    }\r\n}\r\n<\/pre>\n
One way to understand this query is that findEmployee<\/span> is the query exposed by the GraphQL API and will be usually given to you by the developer. This findEmployee<\/span> takes one parameter called email. Since emails are unique, the API will return at most one node. You are creating a query called FindEmployeeByEmail (call it whatever you want!) that passes $email to the findEmployee<\/span> query. You are also saying you just want the employee’s Skype and GitHub ids.<\/p>\n
If all goes well, you should see the following output:<\/p>\n
\"GraphQL <\/p>\n
\n
3. GraphQL query using Python<\/a><\/h3>\n
We can do the same things using Python and requests<\/a> too. Accessing a GraphQL API using the requests module is very similar to accessing a REST API using the requests module. We just pass the query as part of the json argument to requests.some_http_method(). I will not explain the code here since this article is already pretty long. But this is an example Python script I wrote to query all employees. Hopefully, you notice that this is just an auth step plus a GET request that passes a query parameter that looks pretty much exactly like the query you would write on a GraphiQL editor. <\/p>\n
File 1: sample_gql_query.py<\/h4>\n
\r\n\"\"\"\r\nTest to query the Employee GraphQL endpoint\r\n\"\"\"\r\nimport requests\r\nimport json\r\nimport user_credentials as credentials\r\nBASE_URL = 'http:\/\/localhost:5000\/graphql'\r\n\r\ndef authenticate():\r\n    \"Return an authenticate code\"\r\n    query = f\"\"\"mutation {{\r\n        auth(password: \"{credentials.PASSWORD}\", username: \"{credentials.USERNAME}\") {{\r\n            accessToken\r\n            refreshToken\r\n            }}\r\n        }}\r\n    \"\"\"\r\n    response = requests.post(url = BASE_URL, json = {'query': query})\r\n\r\n    return response.json().get('data',{}).get('auth',{}).get('accessToken',None)\r\n\r\ndef test_query_all():\r\n    \"Query allEmployees\"\r\n    query = \"\"\"query\r\n    findAllEmployees{\r\n        allEmployees{\r\n            edges{\r\n                node{\r\n                    email\r\n                    employeeId\r\n                    dateJoined\r\n                    isActive\r\n                    blogAuthorName\r\n                }\r\n            }\r\n        }\r\n    }\"\"\"\r\n    access_token = authenticate()\r\n    print(f'Access token: {access_token}')\r\n    headers = {'Authorization': f'Bearer {access_token}'}\r\n    response = requests.get(url = BASE_URL, json = {'query': query}, headers =\\\r\n        headers)\r\n    all_employees = response.json().get('data', {}).get('allEmployees', {}).get('edges', [])\r\n    for employee in all_employees:\r\n        print(employee)\r\n\r\n\r\n#---START OF SCRIPT\r\nif __name__==\"__main__\":\r\n    test_query_all()\r\n<\/pre>\n
File 2: user_credentials.py<\/h4>\n
Place this file in the same folder as File 1 (sample_gql_query.py).<\/p>\n
\r\nUSERNAME='user1'\r\nPASSWORD='password1'\r\n<\/pre>\n
Note 1: You should not be authenticating with every request. Authenticate once and the token will be valid for 30-minutes.
\nNote 2: You will decide the data structure used in File 2 (user_credentials.py) depending upon the number of users that your tests need. For only one user, what is shown here is more than enough.<\/p>\n
\n
Hopefully you managed to follow along to the end. If you are very new to GraphQL, you are probably feeling like you did not understand head or tail of what just happened. That’s ok – what you just did now forms a solid base for you to start understanding the more theoretical introductions to GraphQL that are available on the Internet. There are also some excellent practical examples for larger datasets (e.g.: movies) that you are (hopefully!) now in a position to tackle better. Some possible next steps for you include Googling how to construct queries, understand mutations, figure out the GraphQL API by looking at code, etc.<\/p>\n
If you got stuck in any of the steps, post a comment below and someone from Team Qxf2 will help you out!<\/p>\n
\n","protected":false},"excerpt":{"rendered":"
I wrote (and open sourced) a Flask app with a GraphQL API that was implemented using Graphene. The application is similar to the official Graphene example but includes the following: 1. JWT authentication 2. An example of filtering 3. A minimal amount of data for people to tinker with the app This article is suitable for: a) Testers looking to […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[172,288,287],"tags":[],"class_list":["post-15280","post","type-post","status-publish","format-standard","hentry","category-flask","category-gql","category-graphql"],"_links":{"self":[{"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/posts\/15280","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/comments?post=15280"}],"version-history":[{"count":29,"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/posts\/15280\/revisions"}],"predecessor-version":[{"id":15321,"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/posts\/15280\/revisions\/15321"}],"wp:attachment":[{"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/media?parent=15280"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/categories?post=15280"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/qxf2.com\/blog\/wp-json\/wp\/v2\/tags?post=15280"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}