fastapi un-official tutorial

TL;DR

Need to learn FastAPI, well, fast? This repo shows you how to create unit tests for every tutorial example in the Official FastAPI documentation. The goal of this repo was two-fold, first to learn how to write REST API's in FastAPI and second, how to write unit tests for that REST API. The third goal was to learn modern Python programming, which includes typing, Pydantic, async/await and Python 3.9 features.

Preface

By Anthony Leotta

In this repo, I will work through the (Official FastAPI Tutorial](https://fastapi.tiangolo.com/tutorial/) by creating unit tests for each topic described. I may stray from the Official Tutorial to satisfy my own curiosity.

2/3/2022 Update:

Sometimes is pays to read the source to a project. In the case of FastAPI, every example in the online documentation can be found in a folder named "docs_src", and the unit tests for then are in "tests\test_tutorial". I learned alot from created my repo and creating all the unit test from scratch. After seeing the FastAPI tutorial code and pytest unit tests, I realized that using unit-tests as a learning tool really works. I think looking at code is one thing, but understanding code enough to be able to write unit tests solidifies the concepts on a whole different level. I am going to continue with this repo, even though I am basically doing the same thing that has already been done in FastAPI itself (and probably better).

Setup

Install httpie
```
http --verison
```
Follow Tony's Tricks to setup a fresh anaconda environments called fastapi39.
Activate Python Environment
```
conda activate fastapi39
```
Install package dependencies.
```
pip install -r requirements.txt
```
Test if uvicorn is installed correctly.
```
uvicorn --version
```
If it is, you will see something like this, the version number may vary:
```
Running uvicorn 0.15.0 with CPython 3.9.7 on Windows
```

Running the Tests using Pytest

Just run pytest, that's it.
```
pytest -vv --disable-warnings
```

To run just the fastapi_tutorial tests

pytest -vv --cov-report html  --cov=fastapi_tutorial

To generate a coverage report of all tutorials and playgrounds

pytest -vv --cov-report html  --cov=fastapi_tutorial
pytest -vv --cov-report html  --cov=pydantic_playground --cov-append
pytest -vv --cov-report html  --cov=pytest_playground --cov-append
pytest -vv --cov-report html  --cov=starlette_playground --cov-append
pytest -vv --cov-report html  --cov=typing_playground --cov-append

Which results in a coverage report of all unit tests.

Testing each server with httpie

First Steps
cd fastapi_tutorial
cd ex01_first_steps
uvicorn main:app --reload
use httpie to make a APi request
```
http GET http://127.0.0.1:8000/
```

Which will return

HTTP/1.1 200 OK
content-length: 25
content-type: application/json
date: Fri, 28 Jan 2022 18:04:18 GMT
server: uvicorn

{
    "message": "Hello World"
}

View Interactive API docs
View Alternative Interactive API docs
View OpenAPI Specification and JSON Schema

Testing using VS Code Interactive Step Debugger

Add a debug launch configuration to .vscode\launch.json

{
    "name": "ex01_first_steps",
    "type": "python",
    "request": "launch",
    "module": "uvicorn",
    "cwd": "${workspaceFolder}/fastapi_tutorial/ex01_first_steps",
    "args": [
        "main:app",
        "--reload"
    ],
    "jinja": true
}

Test route @app.post()

make a POST Request

cat data.json | http POST http://127.0.0.1:8000/

Which will return

{
    "method": "POST",
    "request": {
        "email": "[email protected]",
        "name": "Anthony",
        "password": "123456"
    }
}

Test route @app.put()

make a PUT Request

cat data.json | http PUT http://127.0.0.1:8000/

Which will return

{
    "method": "PUT",
    "request": {
        "email": "[email protected]",
        "name": "Anthony",
        "password": "123456"
    }
}

Test route @app.delete()

make a DELETE Request

cat data.json | http DELETE http://127.0.0.1:8000/

Which will return

{
    "method": "DELETE",
    "request": {
        "email": "[email protected]",
        "name": "Anthony",
        "password": "123456"
    }
}

Test route @app.options()
1. make a OPTIONS Request
```
http OPTIONS http://127.0.0.1:8000/
```
Which will return
```
{
    "method": "OPTIONS"
}
```
Test route @app.head()
1. make a HEAD Request
```
http HEAD http://127.0.0.1:8000/
```
Which will return
```
{
    "method": "HEAD"
}
```

Test route @app.patch()

make a PATCH Request

cat data.json | http PATCH http://127.0.0.1:8000/

Which will return

{
    "method": "PATCH",
    "request": {
        "email": "[email protected]",
        "name": "Anthony",
        "password": "123456"
    }
}

Test route @app.trace()

make a TRACE Request
```
http TRACE http://127.0.0.1:8000/
```
Which will return
```
{
    "method": "TRACE"
}
```

ex02_path_parameters

Path Parameters

Running the unit tests

pytest -vv fastapi_tutorial\ex02_path_parameters\test_ex02_path_parameters.py

ex03_query_parameters

Query Parameters

Running the unit tests

pytest -vv fastapi_tutorial\ex03_query_parameters\test_ex03_query_parameters.py

ex04_request_body

Request Body

Running the unit tests

pytest -vv fastapi_tutorial\ex04_request_body\test_ex04_request_body.py

ex05_query_parameters_and_string_validations

Query Parameters and String Validations

Running the unit tests

pytest -vv fastapi_tutorial\ex05_query_parameters_and_string_validations\test_ex05_query_parameters_and_string_validations.py

ex06_path_parameters_and_numeric_validations

Path Parameters and Numeric Validations

Running the unit tests

pytest -vv fastapi_tutorial\ex06_path_parameters_and_numeric_validations\test_ex06_path_parameters_and_numeric_validations.py

ex07_body_multiple_parameters

Body - Multiple Parameters

Running the unit tests

pytest -vv fastapi_tutorial\ex07_body_multiple_parameters\test_ex07_body_multiple_parameters.py

ex08_body_fields

Body - Fields

Running the unit tests

pytest -vv fastapi_tutorial\ex08_body_fields\test_ex08_body_fields.py

ex09_body_nested_models

Body - Nested Models

Running the unit tests

pytest -vv fastapi_tutorial\ex09_body_nested_models\test_ex09_body_nested_models.py

ex10_declare_request_example_data

Declare Request Example Data
There are no unit test for this section
run server
visit Docs

ex11_extra_data_types

Extra Data Types
This is a deceptively deep section. FastAPI's abilities to use different datatypes relieve just how much the Python language itself is in flux. The differences between Python 3.5 to Python 3.11 are different enough to force the FastAPI documentation to include in some cases three versions of the same FastAPi code.
I am going with Python 3.6 and 3.9. Python 3.10 and 3.11 seem stable enough but I cab only fight some many battles at once. I will upgrade this repro to Python 3.11 or 3.12 when the time seems rights.
Extra Data Types

Running the unit tests

pytest -vv fastapi_tutorial\ex11_extra_data_types\test_ex11_extra_data_types.py

ex12_cookie_parameters

Cookie Parameters

Running the unit tests

pytest -vv fastapi_tutorial\ex12_cookie_parameters\test_ex12_cookie_parameters.py

ex13_header_parameters

Header Parameters

Running the unit tests

pytest -vv fastapi_tutorial\ex13_header_parameters\test_ex13_header_parameters.py

Since the TestClient does not allow for duplicate headers to be sent, I will test using httpie.
```
http GET http://127.0.0.1:8000/items2/ X-Token:foo
```

Returns

HTTP/1.1 200 OK
content-length: 26
content-type: application/json
date: Wed, 02 Feb 2022 14:43:43 GMT
server: uvicorn

{
    "X-Token values": [
        "foo"
    ]
}

Sendc duplicate header

http GET http://127.0.0.1:8000/items2/ X-Token:foo X-Token:bar

Returns

HTTP/1.1 200 OK
content-length: 32
content-type: application/json
date: Wed, 02 Feb 2022 14:44:57 GMT
server: uvicorn

{
    "X-Token values": [
        "foo",
        "bar"
    ]
}

To fix this bug the fastapi39\Lib\site-packages\requests\models.py lines 446 to 455 need to look for either a dictionary or a list, because dictionaries do not allow duplicate keys.

def prepare_headers(self, headers):
    """Prepares the given HTTP headers."""

    self.headers = CaseInsensitiveDict()
    if headers:
        for header in headers.items():
            # Raise exception on invalid header value.
            check_header_validity(header)
            name, value = header
            self.headers[to_native_string(name)] = value

ex14_response_model

Response Model

Running the unit tests

pytest -vv fastapi_tutorial\ex14_response_model\test_ex14_response_model.py

ex15_extra_models

Extra Models

Running the unit tests

pytest -vv fastapi_tutorial\ex15_extra_models\test_ex15_extra_models.py

ex16_response_status_code

Response Status Code

Running the unit tests

pytest -vv fastapi_tutorial\ex16_response_status_code\test_ex16_response_status_codes.py

ex17_form_data

Form Data

Running the unit tests

pytest -vv fastapi_tutorial\ex17_form_data\test_ex17_form_data.py

ex18_request_files

Request Files

To run unit tests.

pytest -vv fastapi_tutorial\ex18_request_files\test_ex18_request_files.py

MIME Types

Test Upload One File at a Time

Pick the ex18_request_files launch target from the VS Code Debug Launch drop-down

The launch configuration is shown below:

{
    "name": "ex18_request_files",
    "type": "python",
    "request": "launch",
    "module": "uvicorn",
    "cwd": "${workspaceFolder}/fastapi_tutorial/ex18_request_files",
    "args": ["main:app", "--reload"],
    "jinja": true
}

Click the green triangle launch button
The FastAPI server should start up and messages will appear in the terminal.
Test with httpie
1. cd to the images folder
2. http --form POST http://localhost:8000/files/ file@PIA09258_callisto.jpg
3. I set a break point on line 9 of
4. The response was
```
HTTP/1.1 200 OK
content-length: 19
content-type: application/json
date: Wed, 02 Feb 2022 22:49:47 GMT
server: uvicorn

{
    "file_size": 10603
}
```
1. This matches the file size.
2. It worked!
Test with a web browser `. Open a browser to http://localhost:8000/one
1. The webpage to upload one file should be displayed.
2. I have downloaded some public domain images from publicdomainreview.org in a folder names "images", select one of those or your own file to upload. Also some NASA images from NASA are there.
3. upload a file
4. It works!

Upload Multiple Files

Test with httpie
1. cd to the images folder
2. http --form POST http://localhost:8000/files/many/ files@PIA09258_callisto.jpg files@PIA00600_modest.jpg
3. I set a break point on line 9 of
4. The response was
```
HTTP/1.1 200 OK
content-length: 28
content-type: application/json
date: Thu, 03 Feb 2022 01:53:54 GMT
server: uvicorn

{
    "file_sizes": [
        10603,
        31793
    ]
}
```
5. It worked!
Test with a web browser
1. Open a browser to http://localhost:8000/many/
2. The webpage to upload one file should be displayed.
3. Select files to be uploaded
4. It works!
```
{"file_sizes":[60080,59073,57081,48237]}
```

ex19_request_forms_and_files

Request Forms and Files

To run unit tests.

pytest -vv fastapi_tutorial\ex19_request_forms_and_files\test_ex19_request_forms_and_files.py

ex20_handling_errors

Handling Errors

To run unit tests.

pytest -vv fastapi_tutorial\ex20_handling_errors\test_ex20_handling_errors.py
pytest -vv fastapi_tutorial\ex20_handling_errors\test_ex20_handling_errors_plain_exception.py

ex21_path_operation_configuration

Path Operation Configuration

To run unit tests.

pytest -vv fastapi_tutorial\ex21_path_operation_configuration\test_ex21_path_operation_configuration.py

To view API docs
1. Start server
  1. I use a VS Code Launch Configuration named: ex21_path_operation_configuration
2. View Interactive API docs
3. View Alternative Interactive API docs
4. View OpenAPI Specification and JSON Schema

ex22_json_compatible_encoder

JSON Compatible Encoder

To run unit tests.

pytest -vv fastapi_tutorial\ex22_json_compatible_encoder\test_ex22_json_compatible_encoder.py

ex23_body_updates

Body - Updates

To run unit tests.

pytest -vv fastapi_tutorial\ex23_body_updates\test_ex23_body_updates.py

ex26_middleware

Middleware

To run unit tests.

pytest -vv fastapi_tutorial\ex26_middleware\test_ex26_middleware.py

ex27_cors

CORS (Cross-Origin Resource Sharing)

To run unit tests.

pytest -vv fastapi_tutorial\ex27_cors\test_ex27_cors.py

ex28_sql_databases

SQL (Relational) Databases

To run unit tests.

pytest -vv fastapi_tutorial\ex28_sql_databases\test_ex28_sql_databases.py

The unit tests will create a test.db file, which needs to be deleted after each run.
- I need to add a tear down that deletes this file
  - for sqlite this means delete it

ex29_bigger_applications_multiple_files

coming soon

ex30_background_tasks

coming soon

ex31_metadata_and_docs_urls

coming soon

ex32_static_files

coming soon

ex33_testing

coming soon

ex34_debugging

coming soon

ex35_advanced_user_guide_intro

coming soon

ex36_advanced_path_operation_advanced_configuration

coming soon

ex37_advanced_additional_status_codes

coming soon

ex38_advanced_return_a_response_directly

coming soon

ex39_advanced_custom_response_html_stream_file_others

coming soon

ex40_additional_responses_in_openapi

coming soon

ex41_advanced_response_cookies

coming soon

ex42_advanced_response_headers

coming soon

ex43_advanced_response_change_status_code

coming soon

ex44_advanced_advanced_dependencies

coming soon

ex45_advanced_security

coming soon

ex46_advanced_using_the_request_directly

coming soon

ex47_advanced_using_dataclasses

coming soon

ex48_advanced_middleware

coming soon

ex49_advanced_sql_relational_databases_with_peewee

coming soon

ex50_advanced_async_sql_relational_databases

coming soon

ex51_advanced_nosql_distributed__big_data_databases

coming soon

ex52_advanced_sub_applications_mounts

coming soon

ex53_advanced_behind_a_proxy

coming soon

ex54_advanced_templates

coming soon

ex55_advanced_graphql

coming soon

ex56_advanced_websockets

coming soon

ex57_advanced_events_startup_shutdown

coming soon

ex58_advanced_custom_request_and_apiroute_class

coming soon

ex59_advanced_testing_websockets

coming soon

ex61_advanced_testing_dependencies_with_overrides

coming soon

ex62_advanced_testing_a_database

coming soon

ex63_advanced_async_tests

coming soon

ex64_advanced_settings_and_environment_variables

coming soon

ex65_advanced_conditional_openapi

coming soon

ex66_advanced_extending_openapi

coming soon

ex67_advanced_openapi_callbacks

coming soon

ex68_advanced_including_wsgi_flask_django_others

coming soon

ex69_concurrency_and_async_await

coming soon

Resources

Awesome List

Tutorials

FARM Stack (Full Stack with React and MongoDB)

Full Stack with React

Full Stack with Vue

Starter Projects

Github Projects

Pydantic

Code Generator

GitHub - koxudaxi/fastapi-code-generator: This code generator creates FastAPI app from an openapi file.

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.vscode		.vscode
fastapi_tutorial		fastapi_tutorial
images		images
.gitignore		.gitignore
README.md		README.md
ex10_declare_request_example_data.png		ex10_declare_request_example_data.png
pytest.ini		pytest.ini
requirements.txt		requirements.txt

datajango/fastapi-unofficial-tutorial

Folders and files

Latest commit

History

Repository files navigation

fastapi un-official tutorial

TL;DR

Preface

Setup

Running the Tests using Pytest

Testing each server with httpie

Testing using VS Code Interactive Step Debugger

ex02_path_parameters

ex03_query_parameters

ex04_request_body

ex05_query_parameters_and_string_validations

ex06_path_parameters_and_numeric_validations

ex07_body_multiple_parameters

ex08_body_fields

ex09_body_nested_models

ex10_declare_request_example_data

ex11_extra_data_types

ex12_cookie_parameters

ex13_header_parameters

ex14_response_model

ex15_extra_models

ex16_response_status_code

ex17_form_data

ex18_request_files

Test Upload One File at a Time

Upload Multiple Files

ex19_request_forms_and_files

ex20_handling_errors

ex21_path_operation_configuration

ex22_json_compatible_encoder

ex23_body_updates

ex26_middleware

ex27_cors

ex28_sql_databases

ex29_bigger_applications_multiple_files

ex30_background_tasks

ex31_metadata_and_docs_urls

ex32_static_files

ex33_testing

ex34_debugging

ex35_advanced_user_guide_intro

ex36_advanced_path_operation_advanced_configuration

ex37_advanced_additional_status_codes

ex38_advanced_return_a_response_directly

ex39_advanced_custom_response_html_stream_file_others

ex40_additional_responses_in_openapi

ex41_advanced_response_cookies

ex42_advanced_response_headers

ex43_advanced_response_change_status_code

ex44_advanced_advanced_dependencies

ex45_advanced_security

ex46_advanced_using_the_request_directly

ex47_advanced_using_dataclasses

ex48_advanced_middleware

ex49_advanced_sql_relational_databases_with_peewee

ex50_advanced_async_sql_relational_databases

ex51_advanced_nosql_distributed__big_data_databases

ex52_advanced_sub_applications_mounts

ex53_advanced_behind_a_proxy

ex54_advanced_templates

ex55_advanced_graphql

ex56_advanced_websockets

ex57_advanced_events_startup_shutdown

ex58_advanced_custom_request_and_apiroute_class

ex59_advanced_testing_websockets

ex61_advanced_testing_dependencies_with_overrides

ex62_advanced_testing_a_database

ex63_advanced_async_tests

ex64_advanced_settings_and_environment_variables

ex65_advanced_conditional_openapi

ex66_advanced_extending_openapi

ex67_advanced_openapi_callbacks

ex68_advanced_including_wsgi_flask_django_others

ex69_concurrency_and_async_await

Resources

Packages