The flask mvc project is structured for larger projects and consists of modules. The codebase follows the Model View Controller pattern for organizing its modules.

In this project MVC is applied as follows:

Task 1

First you need to fork the template repository into your github account. Start by following the link below.

Open Flask MVC workspace

Make sure you're logged into github then click the "Use this template" button.

Provide repository name then click on the "Create repository from template" button

Next click on the pencil icon to edit the readme.md file. In the file update the gitpod link in the to point to your repository's url which should look like

https://github.com/<username>/<repo_name>

Then scroll down, provide a commit message and then click on the green "Commit Changes" button below to save the changes to the readme file.

Finally you can open your workspace by clicking on your gitpod button.

Views

View files contain routes, they specify the urls supported on the application. Views receive user parameters from requests then send them to controllers then return the output of the controller to the user in the response.

views/users.py

Controllers

Views aren't allowed to talk to models directly so controllers stand between the model and views to handle state changes and business logic.

controllers/users.py

Models

Models are your standard flask sqlalchemy models. Each model should have its own separate file.

models/user.py

controllers/__init__.py

models/__init__.py

views/__init__.py

Inorder to run the project, important configuration information must be supplied. This information must not be stored in the repository.

When the project is run in developer mode i.e. locally or in gitpod, it uses the default config given in App/config.py.


When the project is ran in production mode i.e. on a platform like Render, configuration information is loaded from environment variables which can be set on your host provider.

main.py then checks the host os to resolve the environment variables.

On lines 32-36 the app looks in the OS environment variables for configuration information when it detects that it is running in production mode.

Now that the configuration is set up you can run the project by using the flask cli which is configured via wsgi.py file.

Task 2

Open a new terminal and execute the following command to initialize the database and run the project.

$ flask run

The application should run and be viewable in the browser

The wsgi.py file bootstraps the project from calling the application factory. Additionally, it provides a useful way for us to add custom commands to the flask cli.

For example, wsgi.py has a command for quickly creating users.

Task 3

Create a user by executing the following command

$ flask user create bob bobpass

Note create_user() is a controller that can be reused in a view to be invoked in the browser.

Next we shall add some endpoints to your application. Firstly take a look into views/user.py. You will see a route /api/users.

views/user.py

@user_views.route('/api/users')
def client_app():
    users = get_all_users_json()
    return jsonify(users)

This lets us navigate to /api/users to view a json representation of the user we created on the cli.

Now we want to add a view that lets us create a user from the browser.

Task 4

Then create a view, i.e. a route that calls the create_user controller. Note we need to import our create_user controller.

views/user.py

# inside user.py view
# Views cannot import models but can import controllers
from App.controllers import ( get_users, get_users_json, create_user )

@user_views.route('/newuser/<username>/<password>', methods=['GET'])
def create_user_action(username, password):
    create_user(username, password)
    return jsonify({"message":"User Created"})

Now navigate to /newuser/rick/rickpass, you should get the following response.

Navigating back to api/users would show data for both users.

Next we will look at testing the new endpoints in postman by creating a collection. But first we want to refactor our previous review to confirm RESTful architecture, that is using a POST request for creating objects.

Task 5

Update our recently created route to the following:

@user_views.route('/api/users', methods=['POST'])
def create_user_action():
    data = request.json # get data from request body
    user = create_user(data['username'], data['password'])
    return jsonify({"message":f" {data['username']} created with id {user.id}"})

Task 6

Now open postman and signup/login. Then create a new collection by clicking "New"

Then selecting collection.

Then name the collection Lab 7

Next click new again and then select the environment. Name the environment as shown below and define a host variable pointing to your applications url in gitpod.

Next click on new again and select request.

Name the new request "Create User" then save it to the collection.

Now ensure the Lab 7 Heroku environment is set then make a post request to the url shown below.

Then change the dropdown to ‘Body' to change the request body.

Set the following dropdowns to raw and JSON and run the request as shown below.

Press send then press save to save the request. You can also press "Save Response" to save the response as an example for documentation.

If you view your app you should see the newly created user!

At this point you should have two requests in your collection. Publishing your collection docs lets you reference it in tests or share the collection.

Task 7

In the toolbar on the left click the menu button next to your collection then select. Publish Docs

This should open a browser tab to Edit the Published Collection. Scroll to the bottom then click "Publish Collection" on the bottom of the page.

Your collection should be now published at the url given.

If you save more requests to your collection your doc site would be updated accordingly.

And that's how you can deploy a flask application on heroku and create a corresponding postman documentation for the server's endpoints.

References & Additional Reading