REST Interfaces and Flask

Dr Ian Cornelius

Hello

Hello (1)

Learning Outcomes

Understand the concept of Representational State Transfer (REST) and the Flask module
Demonstrate your knowledge of REST interfaces in a body of work
Demonstrate your knowledge of Flask in a body of work

RESTful Interfaces

RESTful Interfaces (1)

Abbreviation for: Representational State Transfer
- also commonly referred to as a RESTful API
An architectural style for providing standards between computer systems and the web
Characterised by being stateless
Concerned with the separation of client and server
- both the client and server can be developed independently
- changes on either platform will not affect each other
REST works with resources and not commands
- a resource is an object or document
- no reliance upon interfaces

REST or Representational State Transfer is an architectural style for providing a standard between computer systems and the web. Most particularly in how we would go about communicating between them to retrieve or manipulate data.

The architecture of REST is design in a manner to be stateless, meaning that the server does not need to know anything about what state the client is in and vice-versa. When it comes to developing a REST system, development can be done in a fashion whereby both the server and client can be implemented separately without knowing about each other.

Essentially, this means that the code on the client side can be changed at any point in time without affecting the operations on the server and vice-versa. The only rule is the formatting of the message that they send to each other, this cannot be changed. By separating the user interface from the data storage, then an improvement can be made on the flexibility of the interface across a multitude of different platforms, in turn, improving the scalability.

As I have mentioned earlier, systems following the REST paradigm are considered to be stateless. As such, with this constraint imposed upon the system, it means that the use of resources is enforced rather than commands. A resource is considered to be the nouns of the web, and they describe any object or document that you may want to store or send to a web service. As a REST system interacts through operations on resources, then they do not rely upon the implementation of an interface.

RESTful Interfaces (2)

Communicating between a Client and a Server i

Client sends a request to receive or modify a resource
Server responds to the request made by a client
A client’s request is made up of the following:
- a HTTP verb
- a header and accept parameter
- path to the resource
- an optional message body

RESTful Interfaces (3)

Communicating between a Client and a Server ii

HTTP Verbs

Four basic HTTP verbs:
1. GET
2. POST
3. PUT
4. DELETE

Headers and Accept Parameters

Sends information about the content to be received from the server
Stipulated inside the Accept field of the header
Defined by a MIME Type:
- application: application/json, application/pdf, application/xml
- audio: audio/mpeg, audio/wav
- image: image/png, image/jpeg, image/gif
- text: text/plain, text/html
- video: video/ogg, video/mp4

There are four basic HTTP verbs that are used in a request to interact with the resources of a REST system. These are:

GET: this retrieves a specific resource or a collection of resources
POST: is used to create a new resource
PUT: is used to update a specific resource
and DELETE is used to remove a specific resource

The header of a client’s request is used to send information about the particular type of content that is able to be received from the server. This is called the Accept field, and it will ensure that the server does not send data that cannot be understood by the client.

The particular options available for the requested content are defined by a MIME type. MIME stands for Multipurpose Internet Mail Extensions and specify the content type. Within the Accept field of the header, the type and subtype of the content being requested is provided. For example, on the screen you can see a collection of MIME types. The first part of a MIME (before the forward slash) denotes what we expect the server to send back to us, in the first case it is an image. After the forward slash is the subtype, and this is how we are expecting the content to be sent back to us; and in this instance it is of the type PNG.

RESTful Interfaces (4)

Communicating between a Client and a Server iii

Paths

Requests must contain a path to the resource
Paths should be designed to ensure the client knows what is happening
- e.g. /modules/5062/
Paths should always contain necessary information to locate the resource
- a degree of specificity if required
POST request to /modules may not need an identifier
- the id is generated on the server-side

When a client sends a request, it must contain a path to the resource that the operation should be performed upon. With the REST, a path should be designed in a manner to help the client know what is happening. Therefore, the first part of the path should be the plural form of the resource, and this ensures that nested paths are simple to read and easy to understand.

For example, a path such as the one shown on the screen is simple to understand by looking at it as it is considered to be hierarchical and descriptive. We can see from just observing the path we wish to access the details of module called 5062.

It should be said that paths should always contain the information that is necessary to locate a resource. It should also be specific if required. For example, if we want to refer to a list or a collection of resources sometimes providing an identification such as 5062 is not required. It may be the case that a POST request will generate an ID for the new object.

RESTful Interfaces (5)

Sending Responses from the Server

Server responses must also include a MIME type
- stored in the content-type of the header
Response data must match what is stored in the Accept field of the client’s request header
Status codes are sent as part of the response
- indicates the success of an operation
- popular status codes are shown in the table below

Status Code	Definition
200 (OK)	Successful operation
201 (CREATED)	Successful creation of an item
204 (NO CONTENT)	Successful operation but no data returned
400 (BAD REQUEST)	Failed operation as bad request was sent
403 (FORBIDDEN)	Failed operation as the client does not have permission
404 (NOT FOUND)	Failed operation as the resource was not found
500 (INTERNAL SERVER ERROR)	Failed operation as an unexpected error occurred

When it comes to a server sending data back to the client, the server is also required to include a MIME type. This would be defined in the content-type of the header. This will alert the client to the type of data that is being sent back in the response body. Just as it was when the client sent the request, the data that is being returned must match one of the MIME types that were stipulated in the Accept field.

Responses that are sent from the server will contain a status code to alert the client about the success of an operation. There are many, many status codes, so we won’t cover them all in this lecture. But some common codes used are:

200 (OK): this is considered to be a standard response when a successful HTTP request has been performed
201 (CREATED): this is the standard response for an HTTP request that resulted in an item being created
204 (NO CONTENT): this is standard response for an HTTP request where nothing was returned in the response body
400 (BAD REQUEST): this means the request was not able to process correctly
403 (FORBIDDEN): the client was unable to access the particular resource due to lack of permission
404 (NOT FOUND): the resource could not be found
500 (INTERNAL SERVER ERROR): this is a generic answer to an unexpected failure if there is no more specific information available

RESTful Interfaces (6)

REST End-Points

REST APIs expose a set of public URLs to access resources of a web service
- these are known as an endpoint
Examples of REST endpoints:

HTTP Verb	API Endpoint	Description
`GET`	/modules	Get a list of modules
`GET`	/modules/	Get a single module
`POST`	/modules	Creates a new module
`PUT`	/modules/	Updates a module
`DELETE`	/modules/	Deletes a module

We have spoken about REST and how they use paths to access a particular resource, etc. These are commonly referred to as endpoints, and are public URLS. On the screen you can see a table of HTTP verbs and a particular API endpoint.

For example, if we were to use a GET request on the endpoint /modules it would return a list of modules for a given course or student. However, if the HTTP verb was changed to POST then it would instead create a new module.

The responses given from these endpoints would be the type of content that is being returned and a particular status code to match the outcome of the operation. Going back to my examples earlier…

If we were to use the GET verb on the endpoint /modules then it would be fair to expect that the returned content-type would be of application/json and if we were able to successfully extract a list of modules then the status code 200 would also be returned.

Flask

Flask (1)

Flask is a third-party module that enables you to build web applications
Based upon the WSGI toolkit and Jinja2 template engine
Often referred to as a micro-framework
- makes use of extensions to add extended functionality
- e.g. database handling and management, form validation etc.

Flask is a framework for developing websites using the Python programming language. It is a third-party module, and it provides you the tools, libraries and technologies that allow you to build a web application. Flask is based upon the WSGI toolkit and Jinja2 template engine.

WSGI stands for “Web Server Gateway Interface” and is the standard adopted by Python for web application development. It is a specification for providing a universal interface between the web server and web applications. Jinja2, on the other hand, is a templating engine that combines a template with a data source to render a dynamic web page.

Flask is often referred to as a micro-framework. What is meant by this is that the aim of the module is to keep the core of an application simple, but extensible. Flask, on its own, does not have a built-in abstraction layer for handling and managing databases, nor does it have any form of method for validating form data. Instead, Flask supports this through extensions to add the required functionality to the application.

You may be accustomed to the DLC website for getting support on modules you study at this university. That website was in fact developed solely using Python and Flask, apart from the obvious HTML for the front-end. Further extensions were used to provide functionality such as databases, user handling, etc.

Flask (2)

Flask Extensions

Extensions can provide additional functionality
- i.e. database handling, form validation and session management
Common extensions are:
- Mail
- SQLAlchemy
- WTF
Installation of an extension is handled via the Python package manager

$ python3 -m pip install Flask-Mail Flask-SQLAlchemy Flask-WTF

As I touched upon earlier, the Flask framework has additional extensions that can enable the developer to handle databases, form validation, and session management. These are only a handful of the extensions that are available, and there are many more. Some common extensions that are used in Flask are:

Flask Mail: this provides an SMTP interface to the application to handle e-mails
Flask SQLAlchemy: this adds the ability to use SQLAlchemy to manage and handle databases
Flask WTF: provides the ability to render forms and provides a level of validation to form data

Installation of these extensions can be performed using the Python package manager, otherwise known as pip. The shell script shown on the screen shows a method of installing the three common extensions discussed in this lecture.

Flask (3)

Flask and Python

Install Flask via the Python package manager
- Note: You should be using virtual environments when working on your Python projects

$ python3 -m pip install Flask

Flask can be imported into the module using the from and import keywords
- i.e. from flask import Flask

When it comes to using Flask, you will need to install the module using the Python package manager. This can be achieved by using the command shown on the screen.

It is important to remember that when you work on a new project in Python, you should be creating a new virtual environment. This enables you to isolate your development projects from the system installed Python and any other Python environments that may exist on the system. A huge benefit is for making your development environment reproducible for other people, especially if you provided a requirements.txt file consisting of all the modules you are using.

Once the Python package has been installed, you can use the module by importing it into your Python script using the from and import keywords. You will notice that the method of importing Flask is not as simple as using import Flask instead, we need to use the from keyword to select the Flask (with an upper ‘f’) from the flask (lower ‘f’) module.

Flask (4)

Creating a Flask Application

A Flask application is created using the Flask class
- i.e. app = Flask(__name__)
Create a function for a simple web-page
- i.e. def hello()
Use a decorator on the function to denote the path/URL of the page
- i.e. @app.route('/')
Run the application on a local development server
- i.e. app.run()
- contains four optional parameters: host, port, debug, and options

from flask import Flask
app = Flask(__name__)

@app.route('/')
def index():
    return "Hello 5062CEM"

if __name__ == '__main__':
    app.run()

You can then proceed to creating your first Flask web application. To create a Flask application, you need to call the Flask class, that is Flask with an upper F and pass through the name of the current module. Getting the name of the current module can be achieved by using the __name__ variable.

This will create an object of the Flask class and store it in the variable appropriately named app. Once our Flask application has been created, we can then move on and create a simple web-page to return the string “Hello 5062CEM”.

To do this, we use the Flask object we created earlier, and use the function route. This is known as a decorator, and it tells the application which URL should be associated with the function below it. Note the @ simple at the beginning of this function call, this denotes that it is a decorator.

The route function takes two parameters:

rule - represents the URL that is being bound to the function
options - a list of parameters that will be forwarded to the underlying rule object

For our simple application, the route we shall be binding to our function is forward slash (/). This is the default landing page for a URL and is often known as the “home page” or “index page”.

Underneath our decorator, we then start writing a function for what we wish to be displayed on our homepage. In the example on the right-hand-side of the screen we can see that a function called hello has been created, and it returns the string Hello 5062CEM!.

Once we have created our homepage, we can run our Flask web application. This can be achieved by calling the Flask object we created earlier and calling the run function on it. The run function consists of four optional parameters, and they are:

host: determine the hostname to listen on, the default hostname is 127.0.0.1
port: determines the port to listen on, the default port is 5000
debug: the default value for this is false; however, if set to true it will provide debugging information; useful for development of more complex web applications
options: a list of options to be forwarded to the server

Now that the general Flask application has been created, you can now run your Python script from the terminal window. When this is done, a message will be displayed in the terminal window telling you that your web application is running and display the hostname and port to connect to view your web-page.

Note that when you are running the server in development mode, that is debug is set to False then the application needs to be restarted manually for any code changes to take effect. That means stopping the Python script from running and then running the script again. However, if you set debug to True in the run function, then the server will reload itself automatically when code changes have been detected.

Flask (5)

Creating a Flask Application with a Template

Flask uses Jinja2 for templating
- a directory called templates will store your Jinja templates
Create a file named index.html with the HTML source of your template
- this should be located in the templates directory
Jinja uses two curly braces ({{ and }}) to dynamically import data from the backend
- between these curly braces will be a variable name
  - i.e. {{ module }}
- this will have been defined as a parameter in the render_template function in the Python source-code

Python Flask Application

from flask import Flask, render_template
app = Flask(__name__)

@app.route('/')
def index():
    return render_template("index.html", module="5062CEM")

if __name__ == '__main__':
    app.run()

HTML Template

<html>
<head>
    <title>{{ module }}</title>
    <style>
        body {
            background-color: magenta;
        }
    </style>
</head>
<body>
Hello {{ module }}!
</body>
</html>

When it comes to using templates to create the basis of your web application, Jinja is most commonly used. Not only does it provide a high-level of code re-use, but it enables you to dynamically insert data from the back-end of the website without the requirement of hard-coding the data yourself.

To begin, you will need to create a directory called templates and this should be located in the route directory of your Python script. You will then want to create a file named index.html and you can use the code I have provided on the screen.

You will see that this HTML source-code has something that looks nothing like HTML, and that is the use of double curly brackets, followed by a variable name. This is the Jinja syntax for accessing data that has been sent by the Flask application. You can see that the variable module has been used in-situ of the title tag, and inside the body tag to display a string Hello {{ module }}.

You can see on the right-hand side of the screen, that our index function has changed slightly. Instead of returning a static string “Hello 5062CEM”, instead we are returning a function called render_template. The function will accept a number of parameters, but in the very first instance it will return the template you wish to use.

For the purpose of this example, we are using our template we have created in the file index.html. You will remember in this template that we have used the Jinja variable module in situ of the title and a greeting to be displayed on the web-page. We can populate this variable with whatever value we wish inside the render_template function as a parameter, and you can see that in the Python code, we have used the string “5062CEM”.

When it comes to running our application, you will now see that our new template has been used (with a fetching pink background) and the text “Hello 5062CEM!” has been displayed. Now this is a basic application and is essentially doing the same as we had previously, albeit instead of returning a static string, we are now using an HTML template.

However, you can do so much more. For example, you could do some processing inside the index function of the Python source and then return the output. Or you can use a Flask extension such as WTF to create a form and then do some processing with the data received from it.

Flask (6)

Creating a Flask Application with a Form

Python Flask Application

from flask import Flask, render_template, request
from flask_wtf import Form
from wtforms import StringField, IntegerField, SubmitField
app = Flask(__name__)
app.secret_key = 'potato'

class SampleForm(Form):
    moduleCode = IntegerField("Code")
    moduleName = StringField("Name")
    school = StringField("School")
    submit = SubmitField("Send")

@app.route('/', methods=['GET', 'POST'])
def index():
    form = SampleForm()
    if request.method == 'POST':
        return f"Form Posted Successfully: Module Name = {request.form.get('moduleName')}"

    return render_template("forms.html", title="An Example of Forms", form=form)

if __name__ == '__main__':
    app.run(debug=True)

HTML Template

<html>
<head>
    <title>{{ title }}</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" integrity="sha384-Zenh87qX5JnK2Jl0vWa8Ck2rdkQ2Bzep5IDxbcnCeuOxjzrPF/et3URy9Bv1WTRi" crossorigin="anonymous">
</head>
<body>
<form action="{{ url_for('index') }}" method="POST">
    {{ form.hidden_tag }}
    <div class="card w-50 m-2">
        <h5 class="card-header">New Module Form</h5>
        <div class="card-body">
            <div class="mb-3 row">
                {{ form.moduleName.label(class="col-sm-2 col-form-label fw-bold") }}
                <div class="col-sm-10">
                    {{ form.moduleName(class="form-control") }}
                </div>
            </div>
            <div class="mb-3 row">
                {{ form.moduleCode.label(class="col-sm-2 col-form-label fw-bold") }}
                <div class="col-sm-10">
                    {{ form.moduleCode(class="form-control") }}
                </div>
            </div>
            <div class="row">
                {{ form.school.label(class="col-sm-2 col-form-label fw-bold") }}
                <div class="col-sm-10">
                    {{ form.school(class="form-control") }}
                </div>
            </div>
        </div>
        <div class="card-footer">
            {{ form.submit(class="btn btn-primary") }}
        </div>
    </div>
</form>
</body>
</html>

This leads nicely onto the final installment of Flask application development, and that is using forms. You should remember from earlier that when it comes to creating a form we can use the extension Flask-WTF. You can see in the Python source-code that we have imported a class called Form from the module flask_wtf. We shall use this class to inherit the functions required for creating a form, whilst providing our own form entities.

You can also see from the Python source-code that we have used the module wtforms to import the following classes:

StringField this provides a method of allowing the user to enter text into the form
IntegerField this provides a method of allowing the user to insert a number into the form
SubmitField this is used to create a button to submit the form

You will also notice that we have used a secret_key after the initialisation of our Flask web application. The secret key is used to keep client-side sessions secure. You can generate a random key, but for the purpose of this insecure application I am going to use the word “potato”.

Below that, you can see that I have created a class called SimpleForm which extends the class Form that we imported earlier from flask_wtf. It is within this class that we create the entities that we require. In this instance, I have created three fields and a single submit button. Each of these fields will ask the user to insert some form of data, i.e. a module name, code, and school. You can see that inside each of the StringField and IntegerField we have provided a string. This is a string that will be used as a label when we come to creating or form in the HTML template.

Before we get to the function of our index page, you can see a small amendment has been made to the route function. Here we have added the methods parameter to denote that our index page will be handing both GET and POST requests.

Let’s move on and look at our index function, as this has changed somewhat considerably. You can see that inside our function, we create an instance of our sample form, and I have aptly named it form. Below this, we do a check to determine whether the request made on the page has been in the form of a POST request. If this were the case, then we would return a static string to highlight the form was posted successfully and provide the output of an entry from the form. Now, this would be something a little more intuitive than printing to a screen, such as populating the details into a database etc. However, for the purpose of this example, we shall just print the information to the screen.

Otherwise, if the page request is in the form of a GET request, then we shall return our forms.html template. You can see that the render_template function has two additional parameters passed through, and that is the title of the web-page and the form itself. We pass the form through to our Jinja template, so we are able to create the form on our HTML web-page.

To the right-hand-side of the screen, you can see the HTML source for this example. You will notice that there is some additional work that was undertaken to display the form. You will see that I have also used Bootstrap to provide some additional jazz and styling to our form, but that is not the important part here.

The important aspect of this source-code is the creation of our form. You can see that we use the form HTML tag to denote that we are creating a form. This will consist of the action (that is the URL of our POST request), and in this instance, it is the URL for our index page, which in this instance is just forward-slash. We then provide the forms’ method of action, and in this instance we are using POST.

Directly below that, we use our Jinja syntax to import the hidden_tag of our form. This is an import tag to include as it can mitigate against cross-site request forgery attacks, commonly referred to as CSRF attacks.

Below this, and ignoring my Bootstrap styling, you can see that we insert the label of the form using a Jinja tag. In this instance, we have called our form entity, followed by a period, and then the name of the form entity we want to include. These names will refer to the variable names we have used for creating our form in the class earlier. Remember that we used moduleName as our variable name to create a string field? Well you can see in our HTML template we have called form.moduleName.label to return the label. Below this, we can then call the input of our form by just calling: form.moduleName and this will create our input entity, which will only accept strings.

This method has been repeated for each of the other input entities: moduleCode and school. We finally then provide the submit button at the end of our form to enable the user to submit our form. With this all put together, we then get something like this…

Talk-through the Example

Flask (7)

Creating a RESTful Interface within a Flask Application

from flask import Flask, jsonify, make_response
app = Flask(__name__)

modules = [
    {"code": "5062CEM", "title": "Programming and Algorithms 2", "leader": "Dr Ian Cornelius"},
    {"code": "4061CEM", "title": "Programming and Algorithms 1", "leader": "Dr Ian Cornelius"}
]

@app.route("/modules", methods=['GET'])
def list_modules():
    response = make_response(jsonify(modules), 200)
    response.headers['Content-Type'] = "application/json"
    return response

@app.route("/modules/<id>", methods=['GET'])
def list_modules_by_id(id):
    for i in range(len(modules)):
        if modules[i]['code'] == id:
            response = make_response(jsonify(modules[i]), 200)
            response.headers['Content-Type'] = "application/json"
            return response
    response2 = make_response("Resource not found.", 200)
    response2.headers['Content-Type'] = "text/html"
    return response2

if __name__ == "__main__":
    app.run(debug=True)

Finally, we can get to the point of this entire lecture. RESTful interfaces. On the screen you can see a simple Flask application that has been designed to return some data about a given module on your course at Coventry University.

You will see in this example that we have imported an additional class from the flask module, known as jsonify and this will make more sense later.

As usual, we create our Flask application by using the Flask class and providing the name of our module. This has been assigned to our variable called app. Below this, we apply a configuration profile to our application, and in this instance we have chosen the option: JSONIFY_PRETTYPRINT_REGULAR and set this value to True. This will ensure that when we return data in a JSON format, it will be displayed appropriately in the web application, i.e. new lines will be created where necessary.

Below this, we have created a list, which consists of two dictionary objects. Each of these dictionary items consists of data relating to the two programming modules on this course. You can interpret this to be my “database” and I use that term loosely.

Below my “database” we have two functions. The first function has a URL endpoint of /modules. I think you can see where we are going with this… When we visit this URL, it will return the list of modules that we created earlier. You can see that I have wrapped the variable with the function jsonify which we imported earlier. This will ensure that the data is returned in a JSON format, which makes it easier for another developer to work with the data that has been returned.

Our second function, has the same URL endpoint, but goes one stage further and accepts an id as a parameter. The id in this instance will be our module code. For example, if I were to enter the URL as /modules/5062CEM then it will return the details for that particular module, as you can see from the code within the function itself. However, if a module code was not valid, then the string “Not Found” will be returned to the user. Let’s have a look at this script in action.

REST Interfaces and Flask

Dr Ian Cornelius

Hello

Hello (1)

Learning Outcomes

RESTful Interfaces

RESTful Interfaces (1)

RESTful Interfaces (2)

Communicating between a Client and a Server i

RESTful Interfaces (3)

Communicating between a Client and a Server ii

HTTP Verbs

Headers and Accept Parameters

RESTful Interfaces (4)

Communicating between a Client and a Server iii

Paths

RESTful Interfaces (5)

Sending Responses from the Server

RESTful Interfaces (6)

REST End-Points

Flask

Flask (1)

Flask (2)

Flask Extensions

Flask (3)

Flask and Python

Flask (4)

Creating a Flask Application

Flask (5)

Creating a Flask Application with a Template

Python Flask Application

HTML Template

Flask (6)

Creating a Flask Application with a Form

Python Flask Application

HTML Template

Flask (7)

Creating a RESTful Interface within a Flask Application

Goodbye

Goodbye (1)

Questions and Support