FastAPI + Deta = ⚡️

Cover Photo by Chris Ried on Unsplash

FastAPI is a a Python Framework for building RESTful APIs. It has all the simplicity of Python with a added advantages of Async⚡️, automatic Schema Generation and OpenAPI and Python Types✨(with Pydantic). FastAPI is relatively a new Project and is gaining quite a good traction in the Dev world. It has got nearly 16k stars on GitHub and about 160 contributors. The main plus side of FastAPI is the documentation which is Top Notch.

Deta is a company that is building a cloud platform which is developer friendly and to reduce the hassle from idea to app.

"Deta is building a cloud for the developers with less build "bells and whistles", only what's needed to get the job done – a Micro Cloud."

Personally what attracted me to deta was the ease to implement. I was having a hard time to connect FastAPI with SQLalchemy since I am a noob. Then Deta entered or at least then I came to know about it.

I was skeptical at first, but the simplicity of working with Deta amazed me and their Slack community is ✨. The creators are almost active everytime and they will help you in anyway possible to overcome an issue.

What we'll build

We're going to build a Personal Mailing List API with

• FastAPI for the API and Logic
• Deta.sh as our DB
• Deploy it on Deta Micros

We're only going to build the API, you can use Mailgun or SendGrid to send the emails. Our API will consist of 4 Operations.

• Add a new Person to our List
• Get all the emails from our list
• Update the email of a specific user in our List
• Delete a Subscriber/User from our List

Setting up FastAPI and Deta

Hope you have Python 3.6+ interpreter on your machine. If you don't make sure to download it and install and verify by running python in your terminal

$ python3
Python 3.7.6 (default, Dec 30 2019, 19:38:26)
[Clang 11.0.0 (clang-1100.0.33.16)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

The above output is on my machine and it will change from machine to machine.

Next thing is to have a folder and a virtual environment, for that we could use either Pipenv or venv. Pipenv is a package for handling and managing Python envs automatically, you can install pipenv with,

$ pip install --user pipenv

Once we installed Pipenv to set up our environment follow the commands to install

• FastAPI
• Uvicorn - The ASGI Server
• Deta - Python Wrapper for the Deta Bases

$ mkdir mailing-list
$ cd mailing-list
$ pipenv shell #it will make the virtual environment
$ pipenv install fastapi uvicorn deta

If we're using venv, then for creating a venv and installing the packages, follow

$ mkdir mailing-list
$ cd mailing-list
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install fastapi uvicorn deta

These are for Unix like systems and on Windows to activate a Virtualenv follow,

venv\Scripts\activate

Once we have set up our Dev Environment. Let's move on to building the Mailing List.

For Deta, create an Account in Deta and create a new Project and get the Project Key. Save the Project key since it will be shown once. You can save it as an environment variable by executing the below code in Unix like(Linux/Mac).

export DETA_PROJECT_KEY = <project key>

and on Windows, use

set DETA_PROJECT_KEY = <project key>

We'll also save the key in a .env file. This env file s important for the deployment process. For that we need to create a file called .env and save the Project Key like

DETA_PROJECT_KEY = <project key>

That's it. Lets move on to the code

The Code

Let's start by making a simple REST API endpoint with FastAPI on a file called main.py

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def helloworld():
    return "Hello World"

This is just a hello world app with FastAPI and for running this, we'll need uvicorn. Execute the following in the terminal/cmd,

$ uvicorn main:app --reload
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [13050] using statreload
INFO:     Started server process [13052]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Our API will be actve the port 8000. FastAPI has inbuilt support for OpenAPI, Swagger and Redoc. To view the docs for our App, just go to localhost:8000/docs. To check if our endpoint works, just execute

$ curl http://127.0.0.1:8000/
"Hello World"

So now, let's move on to our main parts

New Subscriber

We'll be using the docs by Deta for all references.

We need to create a new endpoint for a someone to subscribe to our Mailing List. So we'll just need the Person's Name and Email to be in our DB.

Take care that in some countries its illegal to send emails to people without consent. We'll make a delete endpoint for them to delete themselves from the list

Let's get on to the code for adding a new subscriber to our list. The Python code without the use of a DB or simply the code with FastAPI.

# main.py

from fastapi import FastAPI
from pydantic import BaseModel, NameEmail

app = FastAPI()

class Subscriber(BaseModel):
    full_name: str
    email: NameEmail

@app.post("/subscribe")
async def newUser(sub: Subscriber):
    name = sub.full_name
    email = sub.email

    # you could also return sub.json() or sub.dict()
    return {
        "full_name": name,
        "email": email
    }

We're using Pydantic BaseModel class to inherit our Subscriber class. Then we make the subscriber class a dict to fetch data from the request's body. NameEmail will help us get the name part of the email.

The output is a NameEmail object which has two properties: name and email. For fred.bloggs@example.com, name property would be "fred.bloggs".

Since we're using NameEmail we'll need to install email-validator to work with it. Just run pip install pydantic[email-validator]

This snippet will return the things that we have provided to it. I have entered the data by going to localhost:8000/docs if you have your server running. Our Output if we provide athul for name and athul@example.com for email will be

{
  "name": "athul",
  "email": "athul@example.com",
}

Now let's connect it with the database, Deta Base in this case. We'll be using Python's os package to get the Project Key. We have save the project key to the env vars and restart the server for it to work.

# main.py

import os
from fastapi import FastAPI
from pydantic import BaseModel, NameEmail
from deta import Deta

deta = Deta(os.getenv("DETA_PROJECT_KEY"))
db = deta.Base("mydb")  # this can be anything related to your use case

app = FastAPI()

class Subscriber(BaseModel):
    full_name: str
    email: NameEmail

@app.post("/subscribe")
async def newUser(sub:Subscriber):
    subscriber = db.put({
        "full_name": sub.full_name,
        "email": sub.email.email,
        "key": sub.email.name
    })

    return subscriber

Here we have imported the deta library and initialized it with a db name. We're specifying a key for the data. This key will be the name part of the email since most times it will be unique. If we don't specify a key, deta will generate a unique key for the record.

You can have multiple DBs with a single project key

We're using Deta's PUT method(/function) to insert our data into our DetaBase. The PUT method will generate a unique key for our data and will be stored if we don't specify a key. The output if we add ourselves a new subscriber with provide John Doe for name and john@example.com for email will be,

{
  "email": "john@example.com",
  "key": "john",
  "full_name": "John Doe"
}

So we have made an endpoint for people to subscribe to our Mailing List 🎉.

Next we'll make an endpoint for people to update a theirs info like their Name or Email.

Update a Subscriber

We'll create a new UpdateSubscriber class for updating a Subscriber's Name or Email. We'll use the get and update methods of deta to fetch and update the data. We'll also raise an error if the record is not found in the base

# main.py

from typing import Optional
from fastapi import NameEmail,HTTPException

class UpdateSub(BaseModel):
    full_name: Optional[str] = None
    email: Optional[NameEmail] = None

@app.patch("/subscriber/{email}")
async def update_sub(upsub: UpdateSub, email: NameEmail):
    sub = db.get(email.name)
    if sub is None:
        raise HTTPException(404,"User Not Subscribed")

    updates = {}
    if upsub.full_name:
        updates["full_name"] = upsub.full_name

    if upsub.email:
        updates["email"] = upsub.email.email

    db.update(updates, key=sub["key"])

    return {"msg": "User Updated"}

This endpoint will update the email or full_name of a subscriber but the caveat here is that the key cannot be changed even if the email is changed. Let's make a new user with the name John Reese(Person of Interest) with an initial email reese@gmail.com. Now let's update his email using this endpoint, for that our request URL will be as follows,

http://localhost:8080/subscriber/reese%40example.com You can see that after the /subscriber in the url, we are passing the original email and this is called a Path Parameter. We use the path paramter and get the name part of it and use it as the Key. For updating the email, we take the new email and update it in our Deta base with the update command. The updates should be in the form of a Python dict. If the operation done is correct, then we'll get a None type in return

Get all Subscribers

This endpoint will send a GET HTTP method for fetching all the data from our Deta-Base. We'll use the fetch function/method of deta to retreive all the data from our base. The fetch function will return a generator type, so we'll be using the next() function to get all the data as a List. The endpoint will be like

@app.get("/subscribers")
async def get_all_subs():
    return {"subscribers": next(db.fetch())}

The output of the above request will be

{
  "subscribers": [
    {
      "email": "athul@example.com",
      "key": "athul",
      "name": "Athuk"
    },
    {
      "email": "john@example.com",
      "full_name": "John Doe",
      "key": "john"
    },
    {
      "email": "jhreese@gmail.com",
      "full_name": "John Reese",
      "key": "reese"
    }
  ]
}

Now we have setup a Create, Update and Read endpoints. Next we'll look into the Delete operation.

Delete Subscribers

To delete a subscriber, we'll take in the full_name as the input to find the subscriber and if we there is more than one record with the same full_name, we'll fetch the data with email. Then we'll use the delete method to delete the record by getting the key from our records.

# main.py

class DelSub(BaseModel):
    email: Optional[NameEmail]
    full_name: str

@app.delete("/subscribers.del")
async def unsubscribe(unsub: DelSub):
    data = delsub.dict()
    name = data.get('full_name')
    email = data.get('email')
    sub = next(db.fetch({'full_name':name}))
    if len(sub) > 1 or len(sub) == 0:
        sub = next(db.fetch({'email':email.email}))
        if len(sub)==0:
            raise HTTPException(400,"email not found")
    db.delete(sub[0]['key'])
    return {"msg":"Record Deleted"}

The response if a record is deleted will be a Python None type so we respond with a message,

{"msg":"Record Deleted"}

So we have made a CRUD API for a personal mailing list. Now let's deploy it.

Deploy our API

For Deploying our API, we'll need Deta Micros.

Deta Micros(ervers) are a leightweight but scalable cloud runtime tied to an HTTP endpoint. They are meant to get your apps up and running blazingly fast. Focus on writing your code and Deta will take care of everything else.

You need to have Deta Micros' CLI installed in your system. You can install by following the instructions in this link. Once you've installed, we need to login to Deta via the CLI, for that execute the following command

deta login

It'll open a new browser window and will authenticate the CLI. Next we need to start a new micro. We'll also need a requirements.txt for managing our dependencies, for that either you can copy the response for the command pip freeze and paste it in a file called requirements.txt or on *nix systems, you can just execute

pip freeze > requirements.txt

This will paste the output of pip freeze to requirements.txt. Once we have done we need to deploy it to deta using the command. Once we've done this let's create a new micro, for that we can use the deta new command

$ deta new
{
        "name": "mailing-list",
        "runtime": "python3.7",
        "endpoint": "<url>",
        "visor": "enabled",
        "http_auth": "enabled"
}

It will automatically detect that we'll need a Python runtime and will deploy our code and give us a unique link for our Micro.

Yay we have deployed the API, for the details of the micro, just execute the following for details of the micro.

$ deta details
{
        "name": "mailing-list",
        "runtime": "python3.7",
        "endpoint": "<url>",
        "visor": "enabled",
        "http_auth": "enabled"
}

We need to update the environment variable to set our project_key, execute the deta update command like this

$ deta update -e .env
Updating environment variables...
Successfully updated micro's environment variables

You can disable authentication for the API to be publically available, just execute deta auth disable.

$ deta auth disable
Successfully disabled http auth

If we go to our Micro's url we'll see a Hello World response which we wrote as the / endpoint. We can see the OpenAPI spec and the Swagger Documentation, if we go to the /docs url, we'll see a page like this

Yay we have created an API with FastAPI and Deta and Deployed it to the Web.

That leads to the end of this post, here is the whole source code

import os
from typing import Optional
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, NameEmail
from deta import Deta

deta = Deta(os.getenv("DETA_PROJECT_KEY"))
db = deta.Base('mailing-list')

app = FastAPI()

class Subscriber(BaseModel):
    full_name: str
    email: NameEmail

@app.post("/subscribe")
async def newUser(sub:Subscriber):
    data = sub.dict()
    name = data.get("full_name")
    email = data.get("email")
    subscriber= db.put({
        "full_name":name,
        "email":email.email
    },key=email.name)
    return subscriber

@app.get("/subscribers")
async def getAllSubs():
    return {"subscribers":next(db.fetch())}

class UpdateSub(BaseModel):
    full_name: Optional[str] = None
    email: Optional[NameEmail] = None

@app.patch("/subscriber/{email}")
async def updateSub(subscriber:UpdateSub,email:NameEmail):
    data = subscriber.dict()
    new_name = data.get("full_name")
    new_email = data.get("email")
    sub = db.get(email.name)
    if sub is None:
        raise HTTPException(400,"User Not Subscribed")
    if new_email is None:
        update = {"full_name":new_name}
    if new_name is None:
        update = {"email":new_email.email}
    db.update(updates=update,key=sub['key'])
    return {"msg":"User Updated"}
class DelSub(BaseModel):
    email:Optional[NameEmail]
    full_name:str

@app.delete("/subscribers.del")
async def deleteSub(delsub:DelSub):
    data=delsub.dict()
    name = data.get('full_name')
    email = data.get('email')
    sub = next(db.fetch({'full_name':name}))
    if len(sub) > 1 or len(sub) == 0:
        sub = next(db.fetch({'email':email.email}))
        if len(sub)==0:
            raise HTTPException(400,"email not found")
    db.delete(sub[0]['key'])
    return {"msg":"Record Deleted"} 

@app.get("/")
async def helloworld():
    return "Hello World"

Conclusion

This is just a demo for getting started with FastAPI with Deta.sh. You can change the key for your preference or use the key generated automatically by Deta. You can also use the email address as your key but you may need to switch the @ character with something else like a - or _ for its place. If you have any queries or doubts or feedback, you can use the comments section for the same and do let me if this has helped you. Go forth and build awesome stuff ⚡️. Thank You ❤️