Skip to main content

Introduction

The backend uses FastAPI. FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.8+ based on standard Python type hints You can run the api only by running the pnpm run dev command from a terminal within the api directory. Alternatively, you can directly run the run.py file. Do note that there are production configuration made on the run.py file ie. setting PROD=true will configure for the production environment, thus for local development leave the PROD as false.

API structure

The API root directory is structured as follows:

Src directory

The src directory is where all the application code sits. Below briefly explains each folder/file

Root directory

The root directory contains the typical files one would expect to see in a Python project. The below files are worth describing:

Dependencies

Python 3.9

Because the project is being deployed on Vercel, Python version 3.9 must be used as this is the latest supported version of Python. For more information, read the official documentation. If deploying to somewhere other than Vercel, check which version of Python you may use and adjust the project according to your needs.

Haystack

The project uses Haystack to connect to different LLMs. The input is based on the LLM and the input they support ie. text, image or text+image.

Supabase

The project uses Supabase as a database. Since Planetscale removed their free Hobby tier, Supabase has seemed like a good alternative to use. You do not have to use Supabase with the backend, but the project is written from the perspective of using it.
If you are using Supabase, supabase-py-async is already included as a project dependency within the pyproject.toml. If you are not using Supabase, this can be removed.

Poetry

Poetry is used to manage the virtual environment and project dependencies.

Adding your own endpoints

Given the project structure, there are three areas that you must be aware of when adding your own endpoints with new models. The main areas are:
  • Schemas
  • CRUD
  • API

Example: Creation of Spells endpoints

Step 1: Create a schema

1

Add a schema

Add a new schema to the schemas directory.
src/schemas/spell.py
The table_name value needs to be included in the base Spell class. This must be the same as the name of the table created in Supabase. It is used in the CRUD operations to identify the table to work with.
2

Add to __init__.py

To easily import the new Spell classes throughout our application, they need to be added to the src/schemas/__init__.py file.
src/schemas/__init__.py
This allows us to import from src/schemas like so:

Step 2: Setup CRUD operations

Specific CRUD operations can be created for each endpoint. However, generic CRUD operations in src/crud/base.py can also be used without modification.
1

Create CRUD file

src/crud/crud_spell.py
The CRUDSpell class inherits from the CRUDBase class located in src/crud/base.py. The Spell, SpellCreate and SpellUpdate classes are passed to the CRUDBase class to specify the types of data that will be used in the CRUD operations.The operations that will be used in the API endpoints are functions of the CRUDSpell class.Finally, spell is an instance of CRUDSpell. We import this instance to use in the API endpoints like so: spell.get_all(db) or spell.get(db, id=id).
This part of the project is intended to be read-only, however, the SpellCreate and SpellUpdate classes are created in the schema regardless as they are required by the CRUDBase model’s function arguments. CRUDBase can be refactored to have optional parameters, or a read-only version of the CRUDBase class can be created. This is beyond the scope of this project.
2

Add to __init__.py

Similar to setting up the schemas, the CRUDSpell class needs to be added to the src/crud/__init__.py file.
src/crud/__init__.py

Step 3: Create the API endpoints

1

Create the endpoints

Create the endpoints in the src/api/api_v1/endpoints/spells.py file.
src/api/api_v1/endpoints/spells.py
Here we are calling spell object which we setup in step 2.The SessionDep (located in src/api/deps.py) dependency is used to access the database.The response_model parameter is used to specify the type of data that will be returned from the endpoint. This is used to generate TypeScript types for the frontend.
2

Add the endpoint to the router

To include the new endpoints in the API, it must be added to the API router, located in src/api/api_v1/api.py.
src/api/api_v1/api.py

Step 4: Create the table in Supabase

1

Create the table

Create a new table in your Supabase dashboard. It is imperative that the table name matches the table_name value in the Spell class in src/schemas/spell.py.Columns should be added to match the Spell class. For example, we have the following Spell class:
In this example, the table should be named spells (table names are case-sensitive) with the columns id, name, and description.

For data types, id can be automatically assigned - in this example, it is set to a uuid. The name and description fields are strings, therefore their column’s type is set to text. The id column should be the primary key.
You do not need to add the table_name column as this is used in the FastAPI code to identify the table to work with.
2

Seed the table with data

The data can be seeded using the Supabase dashboard by uploading the harry-potter-db-seed-spells.csv file. For a more detailed explanation, please see the official documentation
3

Configure table security

The table security should be configured to allow the FastAPI application to access the data. By default, Supabase will have RLS (Row Level Security) enabled.

If left un-configured, the database will return an empty array. As this is a simple read-only project, I am turning RLS off. However, for true CRUD operations, it should be configured to use authentication which is beyond the scope of this project.

To disable RLS, in the table settings, select configure RLS and then disable RLS.\
4

Add table connection to .env

Once the table has been created, you must ensure that the DB_URL and DB_API_KEY parameters are populated in your .env file located in the root of the API directory.

These values come from the Supabase dashboard by going to settings and then API. Copy the Project URL (DB_URL) and the Project API Key (DB_API_KEY).
DB_USERNAME and DB_PASSWORD should also included in the .env as they are configured in the src/config.py. If you do not include these you will receive an error from Pydantic.

Their inclusion is a pre-cursor to authentication, but they are not actually used in this project scaffold.

Step 5: Test your new endpoints

You can now test your new endpoints using the FastAPI Swagger UI or by making requests to the API.