This is an API built for the purpose of studying the GraphQL technology and its integration with Python and the Flask framework. The library Graphene was used to build it.
This API has two main models: Users and Posts. So, basically the goal here is to create a CRUD for them. It will also be possible to link a post to a user (its creator, in this case).
Go into your work directory and clone this repository:
$ git clone git@github.com:vitumenezes/flask-with-graphql.gitNow you will need to create a virtual environment to correctly run the projet.
There are differents ways to do it, here we will use the standard python lib called venv.
The virtualenv will be created in a folder. And where, leave it? I suggest creating it with a "." in front of the name, for example: .venv. And create it inside the project folder, so we know that that virtual environment belongs to the project itself. It's just a pattern and there are several, use whichever you prefer.
Enter the folder:
$ cd flask-with-graphqlCreate the virtual environment:
$ python -m venv .venvUse Python 3 versions to run this project. You can manage them with Pyenv ;)
Now, activate it:
$ source .venv/bin/activateAfter that, you will now see the active prefix on your terminal:
(.venv) user@hostname$This means that the virtualenv is active. Make shure it is always active while using the project for development purposes.
Now, install the depedencies on requirements.txt: Enter a python interpreter of your choice and import the SQLAlchemy instance from the main.py file
Before running the project, we first need to create the tables in our sqlite database. Enter a python interpreter of your choice and import the SQLAlchemy (called db) instance from the main.py file.
(.venv) $ python
...
>>> from main import db
>>> db.create_all()Now, run it:
(.venv) $ python main.py runserverAccess http://127.0.0.1:5000/graphql to see the interface to write and test graphql queries.
As stated earlier, there are two base models in the API.
Represents the User template to be saved in the database.
Fields:
uuid: ID!
The User identifier. Autofilled
username: String
The User username. Must be unique
password: String
The User password
posts: [PostType]
The User's posts
Represents the Post template to be saved in the database.
Fields:
uuid: ID!
The Posti identifier. Autofilled
title: String
The Post title
body: String
The Post body (content)
authorId: Int
The Post creator identifier
author: UserType
The user who created the post itself
The API offers Create, Update and Delete mutations for User and Post, that is, 6 mutations in total. There are also queries to fetch one or all rows from each model's database table (User and Post).
{
getAllPosts {
uuid
title
body
authorId
author
}
}
Returns all posts from the database.
PARAMS:
not needed
FIELDS:
All fields from Post
The field author has all fields of User.
Example of usage:
{
getAllPosts {
title
body
authorId
}
}
Example of return:
{
"data": {
"getAllPosts": [
{
"title": "Some title",
"body": "content",
"authorId": 2
},
{
"title": "Title",
"body": "Some Body",
"authorId": 7
},
{
"title": "title",
"body": "body",
"authorId": 2
},
{
"title": "Nice Title",
"body": "Cooooteeeennnnt",
"authorId": 4
}
]
}
}{
getAllUsers {
uuid
username
password
posts
}
}
Returns all users from the database.
PARAMS:
not needed
FIELDS:
All fields from User
The field posts has all fields of Post.
Example of usage:
{
getAllPosts {
username
posts {
title
}
}
}
Example of return:
{
"data": {
"getAllUsers": [
{
"username": "edu",
"posts": [
{
"title": "Some title"
},
{
"title": "title"
}
]
},
{
"username": "luiz",
"posts": []
},
{
"username": "lupa",
"posts": [
{
"title": "Nice Title"
},
{
"title": "mvmwdivotu"
}
]
}
]
}
}Returns data from a single user.
PARAMS:
post_id: The Post ID
FIELDS:
All fields from Post
The field author has all User fields.
Example of usage:
{
getUser(userId: 2) {
username
posts {
title
}
}
}
Example of return:
{
"data": {
"getPost": {
"title": "Title",
"body": "Some Body"
}
}
}Returns data from a single user.
PARAMS:
user_id: The User ID
FIELDS:
All fields from User
The field posts has all Post fields.
Example of usage:
{
getUser(userId: 2) {
username
posts {
title
}
}
}
Example of return:
{
"data": {
"getUser": {
"username": "edu",
"posts": [
{
"title": "Some title"
},
{
"title": "title"
}
]
}
}
}Creates a new Post.
PARAMS:
title: The Post title
body: The Post content
username: The username of the user who created the post
FIELDS:
ok: True or False. Informs if the request went well
message: A message stating the status of the request
post: The post created. Has all Post fields
Example of usage:
mutation {
CreatePost (title: "Some Title", body: "Some content", username: "edu") {
ok
message
post {
uuid
}
}
}
Example of return:
{
"data": {
"CreatePost": {
"ok": true,
"message": "Post criado",
"post": {
"uuid": "10"
}
}
}
}Updates an existing Post.
PARAMS:
postId: The Post identifier. Required
title: The new Post title. Not required
body: The new Post body. Not required
FIELDS:
ok: True or False. Informs if the request went well
message: A message stating the status of the request
post: The post updated. Has all Post fields
Example of usage:
mutation {
UpdatePost (postId: 3, title: "Some new Title", body: "Some new content") {
ok
message
post {
uuid
title
body
}
}
}
Example of return:
{
"data": {
"UpdatePost": {
"ok": true,
"message": "Post atualizado",
"post": {
"uuid": "3",
"title": "Some new Title",
"body": "Some new content"
}
}
}
}Deletes an existing Post.
PARAMS:
postId: The Post identifier. Required
FIELDS:
ok: True or False. Informs if the request went well
message: A message stating the status of the request
Example of usage:
mutation {
DeletePost (postId: 3) {
ok
message
}
}
Example of return:
{
"data": {
"DeletePost": {
"ok": true,
"message": "Post removido com sucesso."
}
}
}Creates a new User.
PARAMS:
username: The User username
password: The User password
FIELDS:
ok: True or False. Informs if the request went well
message: A message stating the status of the request
post: The Post created. Has all Post fields
Example of usage:
mutation {
CreatePost (username: "joe", password: "strongpassword") {
ok
message
user {
uuid
username
}
}
}
Example of return:
{
"data": {
"CreateUser": {
"ok": true,
"message": "Criado com sucesso",
"user": {
"uuid": "8",
"username": "joe"
}
}
}
}Updates an existing User.
PARAMS:
postId: The User identifier. Required
username: The new User username. Not required
password: The new User password. Not required
FIELDS:
ok: True or False. Informs if the request went well
message: A message stating the status of the request
post: The User updated. Has all User fields
Example of usage:
mutation {
UpdateUser (userId: 3, username: "joh doe", password: "newstrongpassword") {
ok
message
user {
uuid
username
password
}
}
}
Example of return:
{
"data": {
"UpdateUser": {
"ok": true,
"message": "Usuário atualizado",
"user": {
"uuid": "3",
"username": "joh doe",
"password": "newstrongpassword"
}
}
}
}Deletes an existing User.
PARAMS:
postId: The User identifier. Required
FIELDS:
ok: True or False. Informs if the request went well
message: A message stating the status of the request
Example of usage:
mutation {
DeleteUser (userId: 3) {
ok
message
}
}
Example of return:
{
"data": {
"DeleteUser": {
"ok": true,
"message": "Usuário removido com sucesso."
}
}
}