Imagine that we have to configure the notification messages to be displayed in an OLED (short for Organic Light Emitting Diode) display wired to an IoT device. The IoT device is capable of running Python 3.7.1, Flask 1.0.2, and other Python packages. There is a team writing code that retrieves string messages that represent notifications from a dictionary and displays them in the OLED display wired to the IoT device. We have to start working on a mobile app and a website that has to interact with a RESTful API to perform CRUD operations with string messages that represent notifications.

We don't need an ORM (short for Object-Relational Mapping) because we won't persist the notifications on a database. We will just work with an in-memory dictionary as our data source. It is one of the requirements we have for this RESTful API. In this case, the RESTful Web Service will be running on the IoT device; that is, we will run the Flask development service on the IoT device.

We have chosen Flask because it is an extremely lightweight framework, we don't need to configure an ORM, and we want to start running the RESTful API on the IoT device as soon as possible to allow all the teams to interact with it. We consider that there will be a website that will be coded with Flask too, and therefore, we want to use the same web micro-framework to power the website and the RESTful Web Service. In addition, Flask is an appropriate choice to create a microservice that can run our RESTful API on the cloud.

There are many extensions available for Flask that make it easier to perform specific tasks with the Flask micro-framework. We will take advantage of Flask-RESTful, an extension that will allow us to encourage best practices while building our RESTful API. In this case, we will work with a Python dictionary as the data source. As previously explained, we will work with more complex data sources in forthcoming examples.

First, we must specify the requirements for our main resource—a notification. We need the following attributes or fields for a notification:

• An integer identifier.
• A string message.
• A TTL (short for Time to Live), that is, a duration in seconds that will indicate the time the notification message has to be displayed on the OLED display.
• A creation date and time. The timestamp will be added automatically when adding a new notification to the collection.
• A notification category description, such as Warning or Information.
• An integer counter that indicates the times when the notification message has been displayed on the OLED display.
• A Boolean value that indicates whether the notification message was displayed at least once on the OLED display.

The following table shows the HTTP verbs, the scope, and the semantics for the methods that our first version of the API must support. Each method is composed of an HTTP verb and a scope, and all the methods have a well-defined meaning for all notifications and collections. In our API, each notification has its own unique URL:

Let's consider that http://localhost:5000/service/notifications/ is the URL for the collection of notifications. If we add a number to the previous URL, we identify a specific notification whose ID is equal to the specified numeric value. For example, http://localhost:5000/service/notifications/5 identifies the notification whose ID is equal to 5.

We have to compose and send an HTTP request with the following HTTP verb (POST) and request URL (http://localhost:5000/service/notifications/) to create a new notification. In addition, we have to provide the JSON key-value pairs with the field names and the values to create the new notification. As a result of the request, the service will validate the values provided for the fields, making sure that it is a valid notification and persists it in the in-memory notifications dictionary. The service will return a 201 Created status code and a JSON body with the recently added notification serialized to JSON, including the assigned ID that was automatically generated by the service to the notification object:

POST http://localhost:5000/service/notifications/ 

We have to compose and send an HTTP request with the following HTTP verb (GET) and request URL (http://localhost:5000/service/notifications/{id}) to retrieve the notification whose ID matches the specified numeric value in the place where {id} is written. For example, if we use the http://localhost:5000/service/notifications/23 request URL, the service will retrieve the notification whose ID matches 23 from the dictionary. If a notification is found, the service will serialize the notification object into JSON and return a 200 OK status code and a JSON body with the serialized notification object. If no notification matches the specified ID or primary key, the service will return just a 404 Not Found status:

GET http://localhost:5000/service/notifications/{id} 

We have to compose and send an HTTP request with the following HTTP verb (PATCH) and request URL (http://localhost:5000/service/notifications/{id}) to update one or more fields for the notification whose ID matches the specified numeric value in the place where {id} is written. In addition, we have to provide the JSON key-value pairs with the field names to be updated and their new values. As a result of the request, the service will validate the values provided for the fields, update these fields on the notification that matches the specified ID, and update the notification in the dictionary if it is a valid notification. The service will return a 200 OK status code and a JSON body with the recently updated notification serialized to JSON. If we provide invalid data for the fields to be updated, the service will return a 400 Bad Request status code. If the service doesn't find a notification with the specified ID, the service will return just a 404 Not Found status:

PATCH http://localhost:5000/service/notifications/{id} 

We have to compose and send an HTTP request with the following HTTP verb (DELETE) and request URL (http://localhost:5000/service/notifications/{id}) to remove the notification whose ID matches the specified numeric value in the place where {id} is written. For example, if we use the http://localhost:5000/service/notifications/27 request URL, the service will delete the notification whose ID matches 27. As a result of the request, the service will retrieve a notification with the specified ID from the dictionary. If a notification is found, the service will ask the dictionary to delete the entry associated with this notification object and the service will return a 204 No Content status code. If no notification matches the specified ID, the service will return just a 404 Not Found status.

DELETE http://localhost:5000/service/notifications/{id} 

In the last few years, many large and complex applications started shifting from a monolithic architecture to a microservices architecture. Instead of working with large and extremely complex web services, the microservices architecture proposes developing a collection of smaller, loosely-coupled services to implement all the features required by complex applications in a way that enables and simplifies continuous delivery.

RESTful APIs are essential pieces of the microservices architecture, and Python is extremely popular when shifting to this architecture. Each microservice can encapsulate a RESTful API that fulfills a specific and limited purpose. The microservice is self-contained, it is easy to maintain, and it helps to support continuous delivery.

As happens with any architecture, there are several ways to implement the microservices architecture. We will learn to encapsulate a RESTful API developed with Flask and Python into a microservice. This way, we will be able to leverage our skills by developing RESTful APIs and using them as the essential pieces to build self-contained and easy-to-maintain microservices.

Throughout this book, we will be working with different frameworks, packages, and libraries to create RESTful Web APIs and microservices, and therefore, it is convenient to work with Python virtual environments to isolate each development environment. Python 3.3 introduced lightweight virtual environments and they were improved in subsequent Python versions. We will work with these virtual environments and, therefore, you will need Python 3.7.1 or higher. You can read more about the PEP 405 Python virtual environment, which introduced the venv module, at https://www.python.org/dev/peps/pep-0405. All the examples for this book were tested on Python 3.7.1 on Linux, macOS, and Windows.

Each virtual environment we create with venv is an isolated environment and it will have its own independent set of installed Python packages in its site directories (folders). When we create a virtual environment with venv in Python 3.7 or higher, pip is included in the new virtual environment. Notice that the instructions provided are compatible with Python 3.7.1 or greater. The following commands assume that you have Python 3.7.1 installed on Linux, macOS, or Windows.

First, we have to select the target folder or directory for our lightweight virtual environment. The following is the path we will use in the example for Linux and macOS:

    ~/HillarPythonREST2/Flask01

The target folder for the virtual environment will be the HillarPythonREST2/Flask01 folder within our home directory. For example, if our home directory in macOS or Linux is /Users/gaston, the virtual environment will be created within /Users/gaston/HillarPythonREST2/Flask01. You can replace the specified path with your desired path in each command.

The following is the path we will use in the example for Windows:

    %USERPROFILE%\HillarPythonREST2\Flask01

The target folder for the virtual environment will be the HillarPythonREST2\Flask01 folder within our user profile folder. For example, if our user profile folder is C:\Users\gaston, the virtual environment will be created within C:\Users\gaston\HillarPythonREST2\Flask01. Of course, you can replace the specified path with your desired path in each command.

In Windows PowerShell, the previous path would be:

    $env:userprofile\HillarPythonREST2\Flask01

Now, we have to use the -m option, followed by the venv module name and the desired path, to make Python run this module as a script and create a virtual environment in the specified path. The instructions vary depending on the platform in which we are creating the virtual environment. Thus, make sure you follow the instructions for your operating system.

Open a Terminal in Linux or macOS and execute the following command to create a virtual environment:

    python3 -m venv ~/HillarPythonREST2/Flask01

In Windows, in the Command Prompt, execute the following command to create a virtual environment:

    python -m venv %USERPROFILE%\HillarPythonREST2\Flask01

In case you want to work with Windows PowerShell, execute the following command to create a virtual environment:

    python -m venv $env:userprofile\HillarPythonREST2\Flask01

The previous commands don't produce any output. Any of the previous scripts created the specified target folder and installed pip by invoking ensurepip because we didn't specify the --without-pip option.

Now, we will analyze the directory structure for a virtual environment. The specified target folder has a new directory tree that contains Python executable files and other files that indicate it is a PEP 405 virtual environment.

In the root directory for the virtual environment, the pyenv.cfg configuration file specifies different options for the virtual environment and its existence is an indicator that we are in the root folder for a virtual environment. In Linux and macOS, the folder will have the following main subfolders:

• bin
• include
• lib
• lib/python3.7
• lib/python3.7/site-packages

The following diagram shows the folders and files in the directory trees generated for the Flask01 virtual environment in macOS:

In Windows, the folder will have the following main subfolders:

• Include
• Lib
• Lib\site-packages
• Scripts

The directory trees for the virtual environment in each platform are the same as the layout of the Python installation in these platforms.

The following diagram shows the main folders in the directory trees generated for the virtual environment in Windows:

Now that we have created a virtual environment, we will run a platform-specific script to activate it. After we activate the virtual environment, we will install packages that will only be available in this virtual environment. This way, we will work with an isolated environment in which all the packages we install won't affect our main Python environment.

Run the following command in the Terminal in Linux or macOS. Notice that the results of this command will be accurate if you don't start a shell different to than the default shell in the Terminal session. In case you have doubts, check your Terminal configuration and preferences:

    echo $SHELL  

The command will display the name of the shell you are using in the Terminal. In macOS, the default is /bin/bash, and this means you are working with the bash shell. Depending on the shell, you must run a different command to activate the virtual environment in Linux or macOS.

If your Terminal is configured to use the bash shell in Linux or macOS, run the following command to activate the virtual environment. The command also works for the zsh shell:

    source ~/HillarPythonREST2/Flask01/bin/activate

If your Terminal is configured to use either the csh or tcsh shell, run the following command to activate the virtual environment:

    source ~/HillarPythonREST2/Flask01/bin/activate.csh

If your Terminal is configured to use the fish shell, run the following command to activate the virtual environment:

    source ~/HillarPythonREST2/Flask01/bin/activate.fish

After you activate the virtual environment, the Command Prompt will display the virtual environment root folder name, enclosed in parentheses as a prefix of the default prompt, to remind us that we are working in the virtual environment. In this case, we will see (Flask01) as a prefix for the Command Prompt because the root folder for the activated virtual environment is Flask01.

The following screenshot shows the virtual environment activated in a macOS High Sierra Terminal with a bash shell, after executing the commands shown previously:

As we can see from the previous screenshot, the prompt changed from Gastons-MacBook-Pro:~ gaston$ to (Flask01) Gastons-MacBook-Pro:~ gaston$ following activation of the virtual environment.

In Windows, you can run either a batch file in the Command Prompt or a Windows PowerShell script to activate the virtual environment.

If you prefer the Command Prompt, run the following command in the Windows command line to activate the virtual environment:

    %USERPROFILE%\HillarPythonREST2\Flask01\Scripts\activate.bat

The following screenshot shows the virtual environment activated in a Windows 10 Command Prompt, after executing the commands shown previously:

As we can see from the previous screenshot, the prompt changed from C:\Users\gaston\AppData\Local\Programs\Python\Python36 to (Flask01) C:\Users\gaston\AppData\Local\Programs\Python\Python36 following activation of the virtual environment.

If you prefer Windows PowerShell, launch it and run the following commands to activate the virtual environment. Notice that you must have script execution enabled in Windows PowerShell to be able to run the script:

    cd $env:USERPROFILE
    HillarPythonREST2\Flask01\Scripts\Activate.ps1

The following screenshot shows the virtual environment activated in the Windows 10 PowerShell, after executing the commands shown previously:

It is extremely easy to deactivate a virtual environment generated by means of the process explained previously. Deactivation will remove all the changes made in the environment variables and will change the prompt back to its default message.

In macOS or Linux, just type deactivate and press Enter.

In the Windows Command Prompt, you have to run the deactivate.bat batch file included in the Scripts folder. In our example, the full path for this file is %USERPROFILE%\HillarPythonREST2\Flask01\Scripts\deactivate.bat.

In Windows PowerShell, you have to run the Deactivate.ps1 script in the Scripts folder.

We have followed the necessary steps to create and activate a virtual environment. Now, we will create a requirements.txt file to specify the set of packages that our application requires to be installed in any supported platform. This way, it will be extremely easy to repeat the installation of the specified packages with their versions in any new virtual environment.

Use your favorite editor to create a new text file, named requirements.txt, within the root folder of the recently created virtual environment. The following lines show the content of the file that declares the packages and the versions that our API requires. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/requirements.txt file:

Flask==1.0.2 
flask-restful==0.3.6 
httpie==1.0.0

Each line in the requirements.txt file indicates the package and the version that needs to be installed. In this case, we are working with exact versions by using the == operator because we want to make sure that the specified version is installed. The following table summarizes the packages and the version numbers that we specified as requirements:

Now, we must run the following command on macOS, Linux, or Windows to install the packages and the versions explained in the previous table with pip by using the recently created requirements.txt file. Notice that Flask is a dependency for Flask-RESTful. Make sure you are located in the folder that has the requirements.txt file before running the following command:

pip install -r requirements.txt     

The last lines for the output will indicate all the packages that have been successfully installed, including Flask, flask-restful, and httpie:

Installing collected packages: itsdangerous, click, MarkupSafe, Jinja2, Werkzeug, Flask, aniso8601, six, pytz, flask-restful, chardet, certifi, idna, urllib3, requests, Pygments, httpie
      Running setup.py install for itsdangerous ... done
      Running setup.py install for MarkupSafe ... done
Successfully installed Flask-1.0.2 Jinja2-2.10 MarkupSafe-1.0
Pygments-2.2.0 Werkzeug-0.14.1 aniso8601-3.0.2 certifi-2018.8.24 chardet-3.0.4 click-7.0 flask-restful-0.3.6 httpie-1.0.0 idna-2.7 itsdangerous-0.24 pytz-2018.5 requests-2.19.1 six-1.11.0 urllib3-1.23
  

Neither Flask nor Flask-RESTful includes the declaration of variables for the different HTTP status codes. We don't want to return numbers as status codes. We want our code to be easy to read and understand, and therefore, we will use descriptive HTTP status codes. Specifically, we will take advantage of the support for enumerations added in Python 3.4 to declare a class that defines unique sets of names and values that represent the different HTTP status codes.

First, create a service folder within the root folder for the recently created virtual environment. Create a new http_status.py file within the service folder. The following lines show the code that declares the HttpStatus class that inherits from the enum.Enum class. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/http_status.py file:

from enum import Enum 
 
 
class HttpStatus(Enum): 
    continue_100 = 100 
    switching_protocols_101 = 101 
    ok_200 = 200 
    created_201 = 201 
    accepted_202 = 202 
    non_authoritative_information_203 = 203 
    no_content_204 = 204 
    reset_content_205 = 205 
    partial_content_206 = 206 
    multiple_choices_300 = 300 
    moved_permanently_301 = 301 
    found_302 = 302 
    see_other_303 = 303 
    not_modified_304 = 304 
    use_proxy_305 = 305 
    reserved_306 = 306 
    temporary_redirect_307 = 307 
    bad_request_400 = 400 
    unauthorized_401 = 401 
    payment_required_402 = 402 
    forbidden_403 = 403 
    not_found_404 = 404 
    method_not_allowed_405 = 405 
    not_acceptable_406 = 406 
    proxy_authentication_required_407 = 407 
    request_timetout_408 = 408 
    conflict_409 = 409 
    gone_410 = 410 
    length_required_411 = 411 
    precondition_failed_412 = 412 
    request_entity_too_large_413 = 413 
    request_uri_too_long_414 = 414 
    unsupported_media_type_415 = 415 
    requested_range_not_satisfiable_416 = 416 
    expectation_failed_417 = 417 
    precondition_required_428 = 428 
    too_many_requests_429 = 429 
    request_header_fields_too_large_431 = 431 
    unavailable_for_legal_reasons_451 = 451 
    internal_server_error_500 = 500 
    not_implemented_501 = 501 
    bad_gateway_502 = 502 
    service_unavailable_503 = 503 
    gateway_timeout_504 = 504 
    http_version_not_supported_505 = 505 
    network_authentication_required_511 = 511 
 
    @staticmethod 
    def is_informational(cls, status_code): 
        return 100 <= status_code.value <= 199 
 
    @staticmethod 
    def is_success(status_code): 
        return 200 <= status_code.value <= 299 
 
    @staticmethod 
    def is_redirect(status_code): 
        return 300 <= status_code.value <= 399 
 
    @staticmethod 
    def is_client_error(status_code): 
        return 400 <= status_code.value <= 499 
 
    @staticmethod 
    def is_server_error(status_code): 
        return 500 <= status_code.value <= 599 

The HttpStatus class defines unique sets of names and values that represent the different HTTP status codes. The names use the description as a prefix and the HTTP status code number as a suffix. For example, the 200 value of the HTTP 200 OK status code is defined in the HttpStatus.ok_200 name, and the HTTP 404 Not Found status code is defined in the HttpStatus.not_found_404 name.

In addition, the HttpStatus class declares five static methods that receive any of the HTTP status codes defined in the enumerable as an argument and determines which of the following categories the status code belongs to: informational, success, redirect, client error, or server error.

Now, we will create a simple NotificationModel class that we will use to represent notifications. Remember that we won't be persisting the model in any database or file, and therefore, in this case, our class will just provide the required attributes and no mapping information. Create a new models.py file in the service folder. The following lines show the code that creates a NotificationModel class in the service/models.py file. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/models.py file:

class NotificationModel: 
    def __init__(self, message, ttl, creation_date, notification_category): 
        # We will automatically generate the new id 
        self.id = 0 
        self.message = message 
        self.ttl = ttl 
        self.creation_date = creation_date 
        self.notification_category = notification_category 
        self.displayed_times = 0 
        self.displayed_once = False 

The NotificationModel class just declares a constructor, that is, the __init__ method. This method receives many arguments and uses them to initialize the attributes with the same names: message, ttl, creation_date, and notification_category. The id attribute is set to 0, displayed_times is set to 0, and displayed_once is set to False. We will automatically increment the identifier for each new notification generated with API calls.

Now, we will create a NotificationManager class that we will use to persist the NotificationModel instances in an in-memory dictionary. Our API methods will call methods for the NotificationManager class to retrieve, insert, update, and delete NotificationModel instances. Create a new service.py file in the service folder. The following lines show the code that creates a NotificationManager class in the service/service.py file. In addition, the following lines declare all the imports we will need for all the code we will write in this file. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/service.py file:

from flask import Flask 
from flask_restful import abort, Api, fields, marshal_with, reqparse, Resource 
from datetime import datetime 
from models import NotificationModel 
from http_status import HttpStatus 
from pytz import utc 
 
 
class NotificationManager(): 
    last_id = 0 
    def __init__(self): 
        self.notifications = {} 
 
    def insert_notification(self, notification): 
        self.__class__.last_id += 1 
        notification.id = self.__class__.last_id 
        self.notifications[self.__class__.last_id] = notification 
 
    def get_notification(self, id): 
        return self.notifications[id] 
 
    def delete_notification(self, id): 
        del self.notifications[id] 

The NotificationManager class declares a last_id class attribute and initializes it to 0. This class attribute stores the last ID that was generated and assigned to a NotificationModel instance stored in a dictionary. The constructor, that is, the __init__ method, creates and initializes the notifications attribute as an empty dictionary.

The code declares the following three methods for the class:

• insert_notification: This method receives a recently created NotificationModel instance in the notification argument. The code increases the value for the last_id class attribute and then assigns the resulting value to the ID for the received notification. The code uses self.__class__ to reference the type of the current instance. Finally, the code adds notification as a value to the key identified with the generated ID, last_id, in the self.notifications dictionary.
• get_notification: This method receives the id of the notification that has to be retrieved from the self.notifications dictionary. The code returns the value related to the key that matches the received id in the self.notifications dictionary that we are using as our data source.
• delete_notification: This method receives the id of the notification that has to be removed from the self.notifications dictionary. The code deletes the key-value pair whose key matches the ID received in the self.notifications dictionary that we are using as our data source.

We don't need a method to update a notification because we will just make changes to the attributes of the NotificationModel instance that is already stored in the self.notifications dictionary. The value stored in the dictionary is a reference to the NotificationModel instance that we are updating and, therefore, we don't need to call a specific method to update the instance in the dictionary. However, in case we were working with a database, we would need to call an update method for our ORM, data repository, or database service.

Now, we will create a notification_fields dictionary that we will use to control the data that we want Flask-RESTful to render in our responses when we return NotificationModel instances. Open the service/service.py file created previously and add the following lines to the existing code. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/service.py file:

notification_fields = { 
    'id': fields.Integer, 
    'uri': fields.Url('notification_endpoint'), 
    'message': fields.String, 
    'ttl': fields.Integer, 
    'creation_date': fields.DateTime, 
    'notification_category': fields.String, 
    'displayed_times': fields.Integer, 
    'displayed_once': fields.Boolean 
} 
 
 
notification_manager = NotificationManager() 

We declared the notification_fields dictionary (dict) with key-value pairs of strings and classes declared in the flask_restful.fields module. The keys are the names of the attributes we want to render from the NotificationModel class, and the values are the classes that format and return the value for the field. In the previous code, we worked with the following classes that format and return the value for the specified field in the key:

• fields.Integer: Outputs an integer value.
• fields.Url: Generates a string representation of a URL. By default, this class generates a relative URI for the resource that is being requested. The code specifies 'notification_endpoint' for the endpoint argument. This way, the class will use the specified endpoint name. We will declare this endpoint later in the service.py file. We don't want to include the hostname in the generated URI and, therefore, we use the default value for the absolute Boolean attribute, which is False.
• fields.DateTime: Outputs a formatted date and time string in UTC, in the default RFC 822 format.
• fields.Boolean: Generates a string representation of a Boolean value.

The 'uri' field uses fields.Url and is related to the specified endpoint instead of being associated with an attribute of the NotificationModel class. It is the only case in which the specified field name doesn't have an attribute in the NotificationModel class. The other strings specified as keys indicate all the attributes we want to be rendered in the output when we use the notification_fields dictionary to make up the final serialized response output.

After we declare the notification_fields dictionary, the next line of code creates an instance of the NotificationManager class created previously, named notification_manager. We will use this instance to create, retrieve, and delete NotificationModel instances.

Flask-RESTful uses resources built on top of Flask pluggable views as the main building block for a RESTful API. We just need to create a subclass of the flask_restful.Resource class and declare the methods for each supported HTTP verb.

First, we will create a Notification class that we will use to represent the notification resource. Open the service/service.py file created previously and add the following lines. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/service.py file:

class Notification(Resource): 
    def abort_if_notification_not_found(self, id): 
        if id not in notification_manager.notifications: 
            abort( 
                HttpStatus.not_found_404.value,  
                message="Notification {0} doesn't exist".format(id)) 
 
    @marshal_with(notification_fields) 
    def get(self, id): 
        self.abort_if_notification_not_found(id) 
        return notification_manager.get_notification(id) 
 
    def delete(self, id): 
        self.abort_if_notification_not_found(id) 
        notification_manager.delete_notification(id) 
        return '', HttpStatus.no_content_204.value 
 
    @marshal_with(notification_fields) 
    def patch(self, id): 
        self.abort_if_notification_not_found(id) 
        notification = notification_manager.get_notification(id) 
        parser = reqparse.RequestParser() 
        parser.add_argument('message', type=str) 
        parser.add_argument('ttl', type=int) 
        parser.add_argument('displayed_times', type=int) 
        parser.add_argument('displayed_once', type=bool) 
        args = parser.parse_args() 
        print(args) 
        if 'message' in args and args['message'] is not None: 
            notification.message = args['message'] 
        if 'ttl' in args and args['ttl'] is not None: 
            notification.ttl = args['ttl'] 
        if 'displayed_times' in args and args['displayed_times']
 is not None: 
            notification.displayed_times = args['displayed_times'] 
        if 'displayed_once' in args and args['displayed_once'] is
 not None: 
            notification.displayed_once = args['displayed_once'] 
        return notification 

The Notification class is a subclass of the flask_restful.Resource superclass and declares the following three methods that will be called when the HTTP method with the same name arrives as a request on the represented resource:

• get: This method receives the ID of the notification that has to be retrieved in the id argument. The code calls the self.abort_if_notification_not_found method to abort in case there is no notification with the requested ID. In case the notification exists, the code returns the NotificationModel instance whose id matches the specified id returned by the notification_manager.get_notification method. The get method uses the @marshal_with decorator, with notification_fields as an argument. The decorator will take the NotificationModel instance and apply the field filtering and output formatting specified in the notification_fields dictionary.
• delete: This method receives the ID of the notification that has to be deleted in the id argument. The code calls the self.abort_if_notification_not_found method to abort in case there is no notification with the requested ID. In case the notification exists, the code calls the notification_manager.delete_notification method with the received ID as an argument to remove the NotificationModel instance from our data repository. Then, the code returns a tuple composed of an empty response body and a 204 No Content status code. Notice that the returned status code in the tuple is specified with HttpStatus.no_content_204.value because we want to return the value of the enumerable, which is 204. We used multiple return values in the tuple to set the response code.
• patch: This method receives the ID of the notification that has to be updated or patched in the id argument. The code calls the self.abort_if_notification_not_found method to abort in case there is no notification with the requested ID. In case the notification exists, the code saves the NotificationModel instance whose id matches the specified id returned by the notification_manager.get_notification method in the notification variable. The next line creates a flask_restful.reqparse.RequestParser instance named parser. The RequestParser instance allows us to add arguments with their names and types and then easily parse the arguments received with the request. The code makes four calls to the parser.add_argument method with the argument name and the type of the four arguments we want to parse. Then, the code calls the parser.parse_args method to parse all the arguments from the request and saves the returned dictionary (dict) in the args variable. The code updates all the attributes that have new values in the args dictionary in the NotificationModel instance, which is notification. In case the request didn't include values for certain fields, the code won't make changes to the related attributes because the code doesn't consider the values that are None. The request doesn't need to include the four fields that can be updated with values. The code returns the updated notification. The patch method uses the @marshal_with decorator, with notification_fields as an argument. The decorator will take the NotificationModel instance, notification, and apply the field filtering and output formatting specified in the notification_fields dictionary.

As previously explained, the three methods call the internal abort_if_notification_not_found method, which receives the ID for an existing NotificationModel instance in the id argument. If the received id is not in the keys of the notification_manager.notifications dictionary, the method calls the flask_restful.abort function with HttpStatus.not_found_404.value as the http_status_code argument and a message indicating that the notification with the specified ID doesn't exist. The abort function raises an HTTPException exception for the received http_status_code and attaches the additional keyword arguments to the exception for later processing. In this case, we generate an HTTP 404 Not Found status code.

Both the get and patch methods use the @marshal_with decorator, which takes a single data object or a list of data objects, and applies the field filtering and output formatting specified as an argument. The marshalling can also work with dictionaries (dict). In both methods, we specified notification_fields as an argument and, therefore, the code renders the following fields: id, uri, message, ttl, creation_date, notification_category, displayed_times, and displayed_once.

The following return statement with the @marshal_with(notification_fields) decorator returns an HTTP 200 OK status code because we didn't specify any status code after the returned object (notification):

return notification 

The next line is the code that is actually executed with the @marshal_with(notification_fields) decorator and we can use it instead of working with the decorator:

return marshal(notification, resource_fields), HttpStatus. HttpStatus.ok_200.value 

For example, we can call the marshal function as shown in the previous line, instead of using the @marshal_with decorator, and the code will produce the same result.

Now, we will create a NotificationList class that we will use to represent the collection of notifications. Open the service/service.py file created previously and add the following lines.

The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/service.py file:

class NotificationList(Resource): 
    @marshal_with(notification_fields) 
    def get(self): 
        return [v for v in
notification_manager.notifications.values()] 
 
    @marshal_with(notification_fields) 
    def post(self): 
        parser = reqparse.RequestParser() 
        parser.add_argument('message', type=str, required=True, help='Message cannot be blank!') 
        parser.add_argument('ttl', type=int, required=True,
help='Time to live cannot be blank!') 
        parser.add_argument('notification_category', type=str, required=True, help='Notification category cannot be blank!') 
        args = parser.parse_args() 
        notification = NotificationModel( 
            message=args['message'], 
            ttl=args['ttl'], 
            creation_date=datetime.now(utc), 
            notification_category=args['notification_category'] 
            ) 
        notification_manager.insert_notification(notification)  
        return notification, HttpStatus.created_201.value 

The NotificationList class is a subclass of the flask_restful.Resource superclass and declares the following two methods that will be called when the HTTP method with the same name arrives as a request on the resource represented:

• get: This method returns a list with all the NotificationModel instances saved in the notification_manager.notifications dictionary. The get method uses the @marshal_with decorator, with notification_fields as an argument. The decorator will take each NotificationModel instance in the returned list and apply the field filtering and output formatting specified in notification_fields.
• post: This method creates a flask_restful.reqparse.RequestParser instance named parser. The RequestParser instance allows us to add arguments with their names and types and then easily parse the arguments received with the POST request to create a new NotificationModel instance. The code makes three calls to parser.add_argument, with the argument name and the type of the three arguments we want to parse. Then, the code calls the parser.parse_args method to parse all the arguments from the request and saves the returned dictionary (dict) in the args variable. The code uses the parsed arguments in the dictionary to specify the values for the message, ttl, and notification_category attributes to create a new NotificationModel instance and save it in the notification variable. The value for the creation_date argument is set to the current date and time with time zone information, and therefore, it isn't parsed from the request. Then, the code calls the notification_manager.insert_notification method with the new NotificationModel instance (notification) to add this new instance to the dictionary. The post method uses the @marshal_with decorator with notification_fields as an argument. The decorator will take the recently created and stored NotificationModel instance, notification, and apply the field filtering and output formatting specified in notification_fields. Then, the code returns a tuple composed of the inserted NotificationModel instance and a 201 Created status code. Notice that the returned status code in the tuple is specified with HttpStatus.created_201.value because we want to return the value of the enumerable, which is 201. We used multiple return values in the tuple to set the response code.

The following table shows the method of our classes created previously that we want to be executed for each combination of HTTP verb and scope:

We must make the necessary resource routing configurations to call the appropriate methods and pass them all the necessary arguments by defining URL rules. The following lines create the main entry point for the application, initialize it with a Flask application, and configure the resource routing for the service. Open the previously created service/service.py file and add the following lines. The code file for the sample is included in the restful_python_2_01_01 folder, in the Flask01/service/service.py file:

app = Flask(__name__) 
service = Api(app) 
service.add_resource(NotificationList, '/service/notifications/') 
service.add_resource(Notification, '/service/notifications/<int:id>', endpoint='notification_endpoint') 
 
 
if __name__ == '__main__': 
    app.run(debug=True) 

The code creates an instance of the flask_restful.Api class and saves it in the service variable. Each call to the service.add_resource method routes a URL to a resource, specifically to one of the previously declared subclasses of the flask_restful.Resource superclass. When there is a request to the service and the URL matches one of the URLs specified in the service.add_resource method, Flask will call the method that matches the HTTP verb in the request for the specified class. The method follows standard Flask routing rules.

For example, the following line will make an HTTP GET request to /service/notifications/ without any additional parameters to call the NotificationList.get method:

service.add_resource(NotificationList, '/service/notifications/') 

Flask will pass the URL variables to the called method as arguments. For example, the following line will make an HTTP GET request to /service/notifications/26 to call the Notification.get method, with 26 passed as the value for the id argument:

service.add_resource(Notification, '/service/notifications/<int:id>', endpoint='notification_endpoint')

In addition, we can specify a string value for the endpoint argument to make it easy to reference the specified route in the fields.Url fields. We pass the same endpoint name, 'notification_endpoint', as an argument in the uri field declared as fields.Url in the notification_fields dictionary that we use to render each NotificationModel instance. This way, fields.Url will generate a URI that considers this route.

We just required a few lines of code to configure resource routing and endpoints. The last line just calls the app.run method to start the Flask application, with the debug argument set to True to enable debugging. In this case, we start the application by calling the run method to immediately launch a local server. We could also achieve the same goal by using the flask command-line script. However, this option would require us to configure environment variables and the instructions are different for the platforms that we are covering in this book: macOS, Windows, and Linux.

Now, we can run the service/service.py script that launches Flask's development server to compose and send HTTP requests to our unsecured and simple web API (we will definitely add security later). Execute the following command. Make sure you have the virtual environment activated:

    python service/service.py

The following lines show the output after we execute the previous command. The development server is listening at port 5000:

     * Serving Flask app "service" (lazy loading)
     * Environment: production
       WARNING: Do not use the development server in a production environment.
       Use a production WSGI server instead.
     * Debug mode: on
     * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
     * Restarting with stat
     * Debugger is active!
     * Debugger PIN: 122-606-712
  

With the previous command, we will start the Flask development server and we will only be able to access it in our development computer. The previous command starts the development server in the default IP address, that is, 127.0.0.1 (localhost). It is not possible to access this IP address from other computers or devices connected to our LAN. Thus, if we want to make HTTP requests to our API from other computers or devices connected to our LAN, we should use the development computer IP address, 0.0.0.0 (for IPv4 configurations) or :: (for IPv6 configurations) as the desired IP address for our development server.

If we specify 0.0.0.0 as the desired IP address for IPv4 configurations, the development server will listen on every interface on port 5000. In addition, it is necessary to open the default port 5000 in our firewalls (software and/or hardware) and configure port forwarding to the computer that is running the development server. The same configuration applies whenever we want to run the application on any cloud provider.

We just need to specify '0.0.0.0' as the value for the host argument in the call to the app.run method, specifically, the last line in the service/service.py file. The following line shows the new call to app.run, which launches Flask's development server in an IPv4 configuration and allows requests to be made from other computers and devices connected to our LAN. The line generates an externally visible server. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/service/service.py file:

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

The Flask development server is running on localhost (127.0.0.1), listening on port 5000, and waiting for our HTTP requests. Now, we will compose and send HTTP requests locally in our development computer or from other computers or devices connected to our LAN.

Throughout this book, we will use the following tools to compose and send HTTP requests:

• Command-line tools
• GUI tools
• Python code
• The web browser

We will start with command-line tools. One of the key advantages of command-line tools is that we can easily run again the HTTP requests after we build them for the first time, and we don't need to use the mouse or to tap the screen to run requests. We can also easily build a script with batch requests and run them. As happens with any command-line tool, it can take more time to perform the first requests compared with GUI tools, but it becomes easier once we've performed many requests and we can easily reuse the commands we have written in the past to compose new requests.

Curl, also known as cURL, is a very popular open source command-line tool and library that allows us to easily transfer data. We can use the curl command-line tool to easily compose and send HTTP requests and check their responses.

In macOS or Linux, you can open a Terminal and start using curl from the command line.

In Windows, you can work with curl in the Command Prompt or you can install curl as part of the Cygwin package installation option and execute it from the Cygwin terminal. In case you decide to use the curl command within the Command Prompt, download and unzip the latest version at http://curl.haxx.se/download.html. Then, make sure you include the folder in which the curl.exe file is included in your path to make it easy to run the command.

You can read more about the Cygwin terminal and its installation procedure at http://cygwin.com/install.html. In case you decide to use the Cygwin terminal, use it whenever you have to run the curl command instead of working with the Command Prompt.

We used the requirements.txt file to install the packages for our virtual environment. In this file, we specified httpie as one of the required packages. This way, we installed HTTPie, a command-line HTTP client written in Python that makes it easy to send HTTP requests and uses a syntax that is easier than curl. One of the great advantages of HTTPie is that it displays colorized output and uses multiple lines to display the response details. Thus, HTTPie makes it easier to understand the responses than the curl utility. However, it is very important to mention that HTTPie is slower than curl.

Make sure you leave the Flask development server running. Don't close the Terminal or Command Prompt that is running this development server. Open a new Terminal in macOS or Linux, or a Command Prompt in Windows, and run the following command. It is very important that you enter the ending slash (/) when specified because /service/notifications won't match any of the configured URL routes. Thus, we must enter /service/notifications/, including the ending slash (/). We will compose and send an HTTP request to create a new notification. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd01.txt file:

http POST ":5000/service/notifications/" message='eSports competition starts in 2 minutes' ttl=20 notification_category='Information'

The following is the equivalent curl command. It is very important to use the -H "Content-Type: application/json" option to tell curl to send the data specified after the -d option as application/json instead of the default application/x-www-form-urlencoded option.

The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd02.txt file:

curl -iX POST -H "Content-Type: application/json" -d '{"message":"eSports competition starts in 2 minutes", "ttl":20, "notification_category": "Information"}' "localhost:5000/service/notifications/"

The previous commands will compose and send the POST http://localhost:5000/service/notifications/ HTTP request with the following JSON key-value pairs:

{  
   "message": "eSports competition starts in 2 minutes",  
   "ttl": 20,  
   "notification_category": "Information" 
} 

The request specifies /service/notifications/ and, therefore, it will match '/service/notifications/' and run the NotificationList.post method. The method doesn't receive arguments because the URL route doesn't include any parameters. As the HTTP verb for the request is POST, Flask calls the post method. If the new NotificationModel was successfully persisted in the dictionary, the function returns an HTTP 201 Created status code and the recently persisted NotificationModel serialized to JSON in the response body. The following lines show an example response for the HTTP request, with the new NotificationModel object in the JSON response:

    HTTP/1.0 201 CREATED
    Content-Length: 283
    Content-Type: application/json
    Date: Wed, 10 Oct 2018 01:01:44 GMT
    Server: Werkzeug/0.14.1 Python/3.7.1
    
    {
        "creation_date": "Wed, 10 Oct 2018 01:01:44 -0000",
        "displayed_once": false,
        "displayed_times": 0,
        "id": 1,
        "message": "eSports competition starts in 2 minutes",
        "notification_category": "Information",
        "ttl": 20,
        "uri": "/service/notifications/1"
    }
  

We will compose and send an HTTP request to create another notification. Go back to the Command Prompt in Windows, or the Terminal in macOS or Linux, and run the following command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd03.txt file:

http POST ":5000/service/notifications/" message='Ambient temperature is above the valid range' ttl=15 notification_category='Warning'

The following is the equivalent curl command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd04.txt file:

curl -iX POST -H "Content-Type: application/json" -d '{"message":"Ambient temperature is above the valid range", "ttl":15, "notification_category": "Warning"}' "localhost:5000/service/notifications/"
  

The previous commands will compose and send the POST http://localhost:5000/service/notifications/ HTTP request with the following JSON key-value pairs:

{  
   "message": "Ambient temperature is above the valid range",  
   "ttl": 15,  
   "notification_category": "Warning" 
} 

The following lines show an example response for the HTTP request, with the new NotificationModel object in the JSON response:

    HTTP/1.0 201 CREATED
    Content-Length: 280
    Content-Type: application/json
    Date: Wed, 10 Oct 2018 21:07:40 GMT
    Server: Werkzeug/0.14.1 Python/3.7.1
    
    {
        "creation_date": "Wed, 10 Oct 2018 21:07:40 -0000",
        "displayed_once": false,
        "displayed_times": 0,
        "id": 2,
        "message": "Ambient temperature is above valid range",
        "notification_category": "Warning",
        "ttl": 15,
        "uri": "/service/notifications/2"
    }
  

We will compose and send an HTTP request to retrieve all the notifications. Go back to the Command Prompt in Windows, or the Terminal in macOS or Linux, and run the following command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd05.txt file:

    http ":5000/service/notifications/"

The following is the equivalent curl command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd06.txt file:

    curl -iX GET "localhost:5000/service/notifications/"

The previous commands will compose and send the GET http://localhost:5000/service/notifications/ HTTP request. The request specifies /service/notifications/ and, therefore, it will match '/service/notifications/' and run the NotificationList.get method. The method doesn't receive arguments because the URL route doesn't include any parameters. As the HTTP verb for the request is GET, Flask calls the get method. The method retrieves all the NotificationModel objects and generates a JSON response with all of these NotificationModel objects serialized.

The following lines show an example response for the HTTP request. The first lines show the HTTP response headers, including the status (200 OK) and the content type (application/json). After the HTTP response headers, we can see the details for the two NotificationModel objects in the JSON response:

    HTTP/1.0 200 OK
    Content-Length: 648
    Content-Type: application/json
    Date: Wed, 10 Oct 2018 21:09:43 GMT
    Server: Werkzeug/0.14.1 Python/3.7.1
    
    [
        {
            "creation_date": "Wed, 10 Oct 2018 21:07:31 -0000",
            "displayed_once": false,
            "displayed_times": 0,
            "id": 1,
            "message": "eSports competition starts in 2 minutes",
            "notification_category": "Information",
            "ttl": 20,
            "uri": "/service/notifications/1"
        },
        {
            "creation_date": "Wed, 10 Oct 2018 21:07:40 -0000",
            "displayed_once": false,
            "displayed_times": 0,
            "id": 2,
            "message": "Ambient temperature is above valid range",
            "notification_category": "Warning",
            "ttl": 15,
            "uri": "/service/notifications/2"
        }
    ]
  

After we run the three requests, we will see the following lines in the window that is running the Flask development server. The output indicates that the service received three HTTP requests, specifically two POST requests and one GET request with /service/notifications/ as the URI. The service processed the three HTTP requests, and returned the 201 status code for the first two requests and 200 for the last request:

127.0.0.1 - - [10/Oct/2018 18:07:31] "POST /service/notifications/ HTTP/1.1" 201 -
127.0.0.1 - - [10/Oct/2018 18:07:40] "POST /service/notifications/ HTTP/1.1" 201 -
127.0.0.1 - - [10/Oct/2018 18:09:43] "GET /service/notifications/ HTTP/1.1" 200 -
  

The following screenshot shows two Terminal windows side by side on macOS. The Terminal window on the left-hand side is running the Flask development server and displays the received and processed HTTP requests. The Terminal window on the right-hand side is running http commands to generate the HTTP requests. It is a good idea to use a similar configuration to check the output while we compose and send the HTTP requests:

Now, we will compose and send an HTTP request to retrieve a notification that doesn't exist. For example, in the previous list, there is no notification with an id value equal to 78. Run the following command to try to retrieve this notification. Make sure you use an id value that doesn't exist. We must make sure that the utilities display the headers as part of the response to see the returned status code. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd07.txt file:

    http ":5000/service/notifications/78" 

The following is the equivalent curl command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd08.txt file:

    curl -iX GET "localhost:5000/service/notifications/78"

The previous commands will compose and send the GET http://localhost:5000/service/notifications/78 HTTP request. The request is the same as the previous one we analyzed, with a different number for the id parameter. The service will run the Notification.get method, with 78 as the value for the id argument. The method will execute the code that retrieves the NotificationModel object whose ID matches the id value received as an argument. However, the first line in the NotificationList.get method calls the abort_if_notification_not_found method, which won't find the ID in the dictionary keys, and it will call the flask_restful.abort function because there is no notification with the specified id value. Thus, the code will return an HTTP 404 Not Found status code. The following lines show an example header response for the HTTP request and the message included in the body. In this case, we just leave the default message. Of course, we can customize it based on our specific needs:

    HTTP/1.0 404 NOT FOUND
    Content-Length: 155
    Content-Type: application/json
    Date: Wed, 10 Oct 2018 21:24:32 GMT
    Server: Werkzeug/0.14.1 Python/3.7.1
    
    {
        "message": "Notification 78 not found. You have requested this     
    URI [/service/notifications/78] but did you mean 
    /service/notifications/<int:id> ?"
    }
  

We provide an implementation for the PATCH method to make it possible for our API to update a single field for an existing resource. For example, we can use the PATCH method to update two fields for an existing notification and set the value for its displayed_once field to true and displayed_times to 1. We don't want to use the PUT method because this method is meant to replace an entire notification.

Now, we will compose and send an HTTP request to update an existing notification, specifically, to update the value of two fields. Make sure you replace 2 with the ID of an existing notification in your configuration. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd09.txt file:

http PATCH ":5000/service/notifications/2" displayed_once=true 
displayed_times=1
  

The following is the equivalent curl command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd10.txt file:

curl -iX PATCH -H "Content-Type: application/json" -d '{"displayed_once":"true", "displayed_times":1}' "localhost:5000/service/notifications/2"
  

The previous command will compose and send a PATCH HTTP request with the specified JSON key-value pairs. The request has a number after /service/notifications/ and, therefore, it will match '/service/notifications/<int:id>' and run the Notification.patch method, that is, the patch method for the Notification class. If a NotificationModel instance with the specified ID exists and was successfully updated, the call to the method will return an HTTP 200 OK status code and the recently updated NotificationModel instance serialized to JSON in the response body. The following lines show a sample response:

HTTP/1.0 200 OK 
Content-Length: 279 
Content-Type: application/json 
Date: Thu, 11 Oct 2018 02:15:13 GMT 
Server: Werkzeug/0.14.1 Python/3.7.1 
 
{ 
    "creation_date": "Thu, 11 Oct 2018 02:15:05 -0000", 
    "displayed_once": true, 
    "displayed_times": 1, 
    "id": 2, 
    "message": "Ambient temperature is above valid range", 
    "notification_category": "Warning", 
    "ttl": 15, 
    "uri": "/service/notifications/2" 
} 

Now, we will compose and send an HTTP request to delete an existing notification, specifically, the last one we added. As happened in our last HTTP requests, we have to check the value assigned to id in the previous response and replace 2 in the command with the returned value. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd11.txt file:

    http DELETE ":5000/service/notifications/2"

The following is the equivalent curl command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd12.txt file:

    curl -iX DELETE "localhost:5000/service/notifications/2"

The previous commands will compose and send the DELETE http://localhost:5000/service/notifications/2 HTTP request. The request has a number after /service/notifications/ and, therefore, it will match '/service/notifications/<int:id>' and run the Notification.delete method, that is, the delete method for the Notification class. If a NotificationModel instance with the specified ID exists and was successfully deleted, the call to the method will return an HTTP 204 No Content status code. The following lines show a sample response:

    HTTP/1.0 204 NO CONTENT
    Content-Length: 3
    Content-Type: application/json
    Date: Thu, 11 Oct 2018 02:22:09 GMT
    Server: Werkzeug/0.14.1 Python/3.7.1

So far, we have been working with two terminal-based, or command-line, tools to compose and send HTTP requests to our Flask development server: cURL and HTTPie. Now, we will work with a GUI (short for Graphical User Interface) tool.

Postman is a very popular API testing suite GUI tool that allows us to easily compose and send HTTP requests, among other features. Postman is available as a Chrome App and as a Macintosh App. We can execute it in Windows, Linux, and macOS as a native app. You can download the versions of the Postman app at https://www.getpostman.com/apps.

Now, we will compose and send HTTP requests to localhost:5000 and test the RESTful API with this GUI tool. Postman doesn't support shorthand for localhost and, therefore, we cannot use the same shorthand we have been using when composing requests with HTTPie.

Once you launch Postman, make sure you close the modal that provides shortcuts to common tasks. Select GET request in the + new drop-down menu in the upper-left corner of the Postman main window.

Select GET in the drop-down menu on the left-hand side of the Enter request URL textbox, and then enter localhost:5000/service/notifications/ in this textbox on the right-hand side of the dropdown.

Then, click Send and Postman will display the following information:

• Status: 200 OK.
• Time: The time it took for the request to be processed.
• Size: The response size calculated by adding the body size to the header's size.
• Body: The response body with all the notifications formatted as JSON with syntax highlighting. The default view for the response body is the Pretty view, and it activates syntax highlighting that makes it easy to read JSON code.

The following screenshot shows the JSON response body in Postman for the HTTP GET request to localhost:5000/service/notifications/:

Click on the Headers tab on the right-hand side of the Body and Cookies tabs to read the response headers. The following screenshot shows the layout for the response headers that Postman displays for the previous response. Notice that Postman displays the Status in the right-hand side of the response and doesn't include it as the first line of the headers, as happened when we worked with both the curl and http command-line utilities:

Now, we will compose and send an HTTP request to create a new notification, specifically, a POST request. Follow these steps:

1. Click on the plus (+) button on the right-hand side of the tab that showed the previous request. This is to create a new tab.
2. Select POST in the drop-down menu on the left-hand side of the Enter request URL textbox, and enter localhost:5000/service/notifications/ in the textbox in the right-hand side of the dropdown.
3. Click Body in the right-hand side of the Authorization and Headers tabs, within the panel that composes the request.
4. Activate the raw radio button and select JSON (application/json) in the dropdown on the right-hand side of the binary radio button. Postman will automatically add a Content-type = application/json header and, therefore, you will notice the Headers tab will be renamed to Headers (1), indicating that there is one key-value pair specified for the request headers.
5. Enter the following lines in the textbox under the radio buttons, within the Body tab. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd13.txt file:

{ 
   "message": "Calculating the most appropriate ambient temperature", 
   "ttl": 20, 
   "notification_category": "Warning" 
}

The following screenshot shows the request body in Postman:

We followed the necessary steps to create an HTTP POST request with a JSON body that specifies the necessary key-value pairs to create a new notification. Click Send and Postman will display the following information:

• Status: 201 Created.
• Time: The time it took for the request to be processed.
• Size: The response size calculated by adding the body size to the header's size.
• Body: The response body, with the recently added notification formatted as JSON with syntax highlighting (Pretty view).

The following screenshot shows the JSON response body in Postman for the HTTP POST request:

Click or tap on the value for the uri field in the JSON response body: /service/notifications/3. You will notice that the value will be underlined when you hover the mouse over it. Postman will automatically generate a GET request to localhost:5000/service/notifications/3, as shown in the following screenshot:

Click Send to run it and retrieve the recently added notification. Notice that the uri field is useful for browsing the API with a tool such as Postman.

One of the nice features included in Postman is that we can easily review and re-run the HTTP requests we have made by browsing the saved History shown on the left-hand side of the Postman window. The History panel displays a list with the HTTP verb, followed by the URL for each HTTP request we have composed and sent. We just need to click on the desired HTTP request and click Send to run it again. The following screenshot shows the many HTTP requests in the History panel with the first one selected to send it again:

JetBrains PyCharm is a very popular multiplatform Python IDE (short for Integrated Development Environment) available on macOS, Linux, and Windows. Its paid professional version includes a REST Client that allows us to easily test RESTful Web Services and microservices. In case we work with this version of the IDE, we can compose and send HTTP requests without leaving the IDE. You don't need a JetBrains PyCharm Professional version license to run the examples included in this book. You can take advantage of the free 30-day trial. However, in case you don't want to install this IDE, you can skip the steps and use the provided http or curl commands, which perform the same task. Because the IDE is very popular, we will learn the necessary steps to compose and send an HTTP request for our API by using the HTTP client included in the editor that replaced the deprecated REST Client.

Now, we will use the HTTP client included in PyCharm Professional to compose and send an HTTP request to create a new game, specifically, a POST request. Follow these steps:

1. Select File | New | HTTP Request in the main menu.
2. Enter notifications_post_pycharm in the Name textbox and click OK. The IDE will create a new file with the http extension and with instructions on how to build HTTP requests.

3. Replace the code with the following lines. The code starts with the HTTP method name, POST, followed by the URL. The following line specifies the header with the value for Content-Type and the next lines provide the JSON body within curly brackets. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/notifications_post_pycharm.http file:

POST http://localhost:5000/service/notifications/ 
Content-Type: application/json 
 
{ 
   "message": "Working with PyCharm Professional", 
   "ttl": 12, 
   "notification_category": "Information" 
} 

The following screenshot shows the request incorporated in PyCharm Professional's editor:

We followed the necessary steps to create an HTTP POST request with a JSON body that specifies the necessary key-value pairs to create a new notification.

Click the run HTTP request button, that is, the first button with the play icon in the upper-left corner of the editor, under the tab's name (notifications_post_1.http). Select Run localhost:5000 in the context menu that is displayed.

PyCharm will compose and send the HTTP POST request, which will activate the Run tab and display the request we made, the response headers, the response body, the response code 201 (Created), the time it took for the request to be processed, and the content length at the bottom of the output. By default, PyCharm will automatically apply JSON syntax highlighting to the response. The following screenshot shows the output in the Run tab for the HTTP POST request:

In case you don't want to work with PyCharm Professional, run any of the following commands to compose and send the HTTP POST request to create the new notification. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd14.txt file:

http POST ":5000/service/notifications/" message='Working with
PyCharm Professional' ttl=12 notification_category='Information'
  

The following is the equivalent curl command. The code file for the sample is included in the restful_python_2_01_02 folder, in the Flask01/cmd15.txt file:

curl -iX POST -H "Content-Type: application/json" -d '{"message":"Working with PyCharm Professional", "ttl":12, "notification_category": "Information"}' "localhost:5000/service/notifications/"
  

Because we made the necessary changes to generate an externally visible Flask development server, we can also use apps that can compose and send HTTP requests from mobile devices to work with the RESTful API.

For example, we can work with the iCurlHTTP App on iOS devices such as iPad Pro, iPad, and iPhone: https://itunes.apple.com/us/app/icurlhttp/id611943891?mt=8. In Android devices, we can work with the HTTP Request App: https://play.google.com/store/apps/details?id=air.http.request&hl=en.

The next screenshot shows the results of composing and sending the following HTTP request with the GET http://192.168.1.106:8000/service/notitications/ iCurlHTTP app. Remember that you have to perform the configurations explained previously in your LAN and router to be able to access the Flask development server from other devices connected to your LAN. In this case, the IP assigned to the computer running the Flask development server is 192.168.1.106 and, therefore, you must replace this IP with the IP assigned to your development computer. At the time this book was published, the mobile apps that allow you to compose and send HTTP requests do not provide all the features you can find in Postman or command-line utilities:

We've built our first RESTful Web Service that is capable of running as a microservice with Flask and Python. We can consume the API with any modern programming language that can compose and send HTTP requests to the resources and verbs supported by the API and work easily with JSON content.

It is extremely important to make sure that we set the content type for the HTTP request as we did when working with the curl and http command-line utilities. We just need to check which is the most convenient way of doing so in the programming language that we have to use as a client.

The fact that we can easily run a Flask development server and check its console output whenever a new request is processed makes it easy to check which requests arrive at the server. In this case, we are working with a basic and unsecured API. However, we will work with secure and more advanced APIs in the forthcoming chapters.

Let's see whether you can answer the following questions correctly:

1. HTTPie is a:
   1. Command-line HTTP server written in Python that makes it easy to create a RESTful Web Server
   2. Command-line utility that allows us to run queries against a SQLite database
   3. Command-line HTTP client written in Python that makes it easy to compose and send HTTP requests

2. Flask-RESTful uses which of the following as the main building block for a RESTful API:
   1. Resources built on top of Flask pluggable views
   2. Statuses built on top of Flask resource views
   3. Resources built on top of Flask pluggable controllers

3. To process an HTTP PATCH request on a resource, which method should we declare in a subclass of flask_restful.Resource?
   1. patch_restful
   2. patch_method
   3. patch

4. To process an HTTP PUT request on a resource, which method should we declare in a subclass of flask_restful.Resource?
   1. put_restful
   2. put_method
   3. put

5. To process an HTTP POST request on a resource, which method should we declare in a subclass of flask_restful.Resource?
   1. post_restful
   2. post_method
   3. post

6. To process an HTTP GET request on a resource, which method should we declare in a subclass of flask_restful.Resource?
   1. get_restful
   2. get_method
   3. get

7. A subclass of flask_restful.Resource represents:
   1. A controller resource
   2. A RESTful resource
   3. A single RESTful HTTP verb

8. If we use the @marshal_with decorator with notification_fields as an argument, the decorator will:
   1. Apply the field filtering and output formatting specified in notification_fields to the appropriate instance
   2. Apply the field filtering specified in notification_fields to the appropriate instance, without considering output formatting
   3. Apply the output formatting specified in notification_fields to the appropriate instance, without considering field filtering

In this chapter, we designed a RESTful API to interact with a simple dictionary that acted as a data repository and performed CRUD operations with notifications, to be used as a baseline for a microservice. We defined the requirements for our API and understood the tasks performed by each HTTP method. We set up a virtual environment with Flask and Flask-RESTful. We followed best practices to generate a reproducible virtual environment.

We created a model to represent and persist notifications. We learned how to configure the serialization of notifications into JSON representations with the features included in Flask-RESTful. We wrote classes that represent resources and process the different HTTP requests, and we configured the URL patterns to route URLs to classes.

Finally, we started the Flask development server and we used command-line tools to compose and send HTTP requests to our RESTful API and analyzed how each HTTP requests was processed in our code. We also worked with many useful GUI tools to compose and send HTTP requests.

Now that we understand the basics of the combination of Flask and Flask-RESTful to create RESTful APIs that we can encapsulate in microservices, in the next chapter, we will expand the capabilities of the RESTful Web API by taking advantage of the advanced features included in Flask-RESTful and related ORMs.