Introduction

The previous article reviewed how to set and read environment variables. We'll use that knowledge and set up an API Key as an environment variable for authorization in a .NET Web API Project. Keys are a variable you would not want to check into your code repo, so environment variables are a perfect place for them. We don't want to store keys in our appsettings.json file, you can also store them in a 3rd party key vault or whatever you prefer outside of your project.

An API Key can serve two main purposes, a method of identifying the caller, client, or requestor of the API Service and also controlling access to the API Service. It is a simple method of security to protect API resources.

API keys are a common approach to auth when using microservices, having internal services communicate with each other.

API keys can be managed in a couple of different ways. For example, one approach is to create client-specific keys. The key can be used to validate the requesting service in order to provide specific access to one service versus another such as rate limiting, read vs write access, performance priority, etc. You need to manage to create multiple keys and assign them to the correct party. That is outside the scope of this article. Another approach is using a static key that can be provided to all API client services for authorization. "One key to rule them all..." this is the use case we'll walkthrough in this article.

Code for this example can be found here - API Key Project Repo. Continuing along with the other articles in this series I'll be building in Visual Studio for Mac using .NET 6.

Setup an API Key Environment Variable

For this walkthrough, we will store the API Key in Visual Studio for Mac's Environment Variable properties.

This project will be a new build from scratch, below are the settings I'm using.

After your new project is scaffolded out, go to the Project's Properties window by either right-clicking the project folder in the solution explorer window or in the menu bar click on Project and select the Properties in the drop-down.

In the Properties window go to the Run > Configurations > Default option and add a new Environment Variable.

⚠️ Environment variables create in Visual Studio are copied to your launchSettings.json file in the projects Properties folder. This file is not in your .gitignore file by default.

Your ENV variables should not be in your code, this is just a development example.

Middleware

We need to add a new directory named Authentication for our changes. We will be creating a middleware that will be injected into the application request pipeline.

.NET Middleware is the pipeline that handles requests and responses in the application. Request Delegates are the individual stops along the pipeline. We use Dependency Injection to add the RequestDelete parameter to our custom middleware class AuthApiKeyMiddleware. Writing custom middleware documentation is available on the Microsoft Docs site.

The InvokeAsync method will add the HttpContext in order to access all the details of the request such as headers, user context, query strings, etc.

The InvokeAsync method will perform two main tasks:

1. Check if the request includes the x-api-key header.

2. If the request does include the x-api-key header, make sure it is valid.

In either case, if the x-api-key header is missing or the value is not valid, the middleware will return an UNAUTHORIZED: 401 response before even hitting our API endpoint.

In the event that the x-api-key is valid, then the request context is passed onto the next delegate in the pipeline.

⚠️ This auth middleware will be applied to all endpoints in the project. If you only want to restrict specific endpoints an Auth Attribute will need to be created instead. We'll cover than later.

using System;
namespace article_3_api_key.Authentication
{
    public class AuthApiKeyMiddleware
    {
        // Request Delete that is used to manage each HTTP request.
        private readonly RequestDelegate _next;
        // API Key Header Name
        private const string ApiKeyHeader = "x-api-key";

        // Inject Request Delegate into API Key Middleware
        public AuthApiKeyMiddleware(RequestDelegate next)
        {
            _next = next;
        }

        // Pass the Request's HTTP Context
        public async Task InvokeAsync(HttpContext context)
        {
            // Look for the "x-api-key" Header in the request
            if(!context.Request.Headers.TryGetValue(ApiKeyHeader, out var extractedApiKey))
            {
                // If not found, throw a 401 status
                // 401 = Invalid or Missing Credentials
                // https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
                context.Response.StatusCode = 401;
                await context.Response.WriteAsync("UNAUTHORIZED: API Key Missing");
                return;
            }

            // Get the real key from our ENV Variable
            var apiVal = Environment.GetEnvironmentVariable(ApiKeyHeader);

            // API Key found in Header
            // Validate the Key
            if(!apiVal.Equals(extractedApiKey))
            {
                // If key is not valid, throw a 401 status
                // 401 = Invalid or Missing Credentials
                // https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
                context.Response.StatusCode = 401;
                await context.Response.WriteAsync("UNAUTHORIZED: Invalid API Key");
            }

            // Valid API Key was provided
            // Pass request to the next delegate in the pipeline
            await _next(context);
        }
    }
}

To use this middleware in the application pipeline, we need to add a single line of code in the Program.cs file. Below is a section of the file showing the use of the new middleware.

// Program.cs FILE
...

// NEW LINE: Add new API KEY Middleware to pipeline
app.UseMiddleware<AuthApiKeyMiddleware>();

app.UseAuthorization();

app.MapControllers();

app.Run();

Start the project to test the changes. Click the play button in the top menu of Visual Studio.

Try it out

I'm going to hit the API using CURL statements... 3 different attempts to see the application's response for the following cases: Missing API Key, Invalid API Key, and Valid API Key.

Missing API Key

curl -X GET http://localhost:5276/WeatherForecast

You should see the following unauthorized response:

Invalid API Key

curl -X GET http://localhost:5276/WeatherForecast  -H 'x-api-key: WrongKey'

You should see the following unauthorized response:

Valid API Key

curl -X GET http://localhost:5276/WeatherForecast  -H 'x-api-key: ThisIsMySecureKey!'

You should see the weather response below.

Swagger Support

If you try hitting the weather endpoint in Swagger you will receive a 401 response. Swagger is not sending the API key along with the request so each request is rejected. Currently, there is no place to add the API Key to your requests. Let's fix that.

In the Programs.cs file update the builder.Services.AddSwaggerGen extension. The code is shown below.

We are specifying the "Security Definition" for an input to build the header named x-api-key.

We then add a Security Requirement based on a scheme that will use the API key header.

// Program.cs
...

builder.Services.AddSwaggerGen(x =>
{
    x.AddSecurityDefinition("Weather API Key", new OpenApiSecurityScheme
    {
        // Header Name
        Name = "x-api-key",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "ApiKeyScheme",
        In = ParameterLocation.Header,
        Description = "API Key Header Requirement"
    });

    x.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Weather API Key"
                },
                // Scheme using Header
                In = ParameterLocation.Header
            },
            new List<string>()
        }
    });
});

...

Let's start up the project and use Swagger.

You will now see a green Authorize button that was not available before.

Click on Authorize and enter your API Key and click Authorize to save your input and Close to close the prompt.

You can now try to execute the endpoint and you will see the weather data returned.

Attributes

For scenarios where the flexibility of securing specific endpoints is required .NET Custom Attributes can be used instead of Middleware. Again, the middleware implemented before was locking down all endpoints for all controllers.

We first need to comment out the line in Program.cs to use the new API Key middleware, we don't want to use that delegate for every API request for this example. We'll use attributes at a Controller (Class) and Endpoint (Method) level of execution to validate the API key.

// Program.cs

...
//app.UseMiddleware<AuthApiKeyMiddleware>();
...

Next, create a new Attribute class, AuthApiKeyAttribute in the Authentication folder.

using System;
using Microsoft.AspNetCore.Mvc.Filters;

namespace article_3_api_key.Authentication
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
    public class AuthApiKeyAttribute : Attribute, IAsyncActionFilter
    {
        // API Key Header and ENV Name
        private const string ApiKeyHeader = "x-api-key";

        public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
        {
            // Look for the "x-api-key" Header in the request
            if (!context.HttpContext.Request.Headers.TryGetValue(ApiKeyHeader, out var apiKeyVal))
            {
                // If not found, throw a 401 status
                // 401 = Invalid or Missing Credentials
                // https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
                context.HttpContext.Response.StatusCode = 401;
                await context.HttpContext.Response.WriteAsync("UNAUTHORIZED: API Key Missing");
            }

            // Get the real key from our ENV Variable
            var apiVal = Environment.GetEnvironmentVariable(ApiKeyHeader);
            if (!apiVal.Equals(apiKeyVal))
            {
                // If not found, throw a 401 status
                // 401 = Invalid or Missing Credentials
                // https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
                context.HttpContext.Response.StatusCode = 401;
                await context.HttpContext.Response.WriteAsync("UNAUTHORIZED: Invalid API Key");
            }

            await next();
        }
    }
}

The new class will specify a base class of Attribute and IAsyncActionFilter. The AttributeUsage decorator is also an Attribute that indicates that this Attribute class will be used on classes (Controllers) and methods (endpoints/ actions).

Outside of the class decorations, the OnActionExecutionAsync method is identical to the middleware example. We are looking to ensure the API key header is included and if it is, make sure it is valid.

To test that the Attribute only works on specific controller endpoints and not all of them, we are going to create a new endpoint.

In the WeatherForecastController, change the attributes on the existing endpoint to use the AuthAPIKey attribute. A using statement will be required to point to the new class file. Another change is that "Secure" is added to the route.

The second endpoint is a copy of the first endpoint. All but the AuthAPIKey Attribute is not specified. The route of this endpoint is "Open".

// WeatherForecastController.cs
using article_3_api_key.Authentication;
...    

[AuthApiKey]
[HttpGet]
[Route("Secure")]
public IEnumerable<WeatherForecast> Get()

...

[HttpGet]
[Route("Open")]
public IEnumerable<WeatherForecast> GetTest()

...

Start up the project and let's explore the changes in Swagger.

Open Endpoint

Without entering your API Key, execute the /WeatherForecast/Open endpoint and you will be able to see the weather data returned with no restrictions.

Secure Endpoint via Attribute

Executing the Secure endpoint will result in a 401 Unauthorized Response without the API key. The Controller will require the Auth API Key Attribute to be run before hitting the endpoint.

Enter your API key and try again, you will see the lock icon activated in Swagger and the data is now returned from a secure route.

End

You now have a working API Key Middleware and Attribute option for a .NET 6 Web API Project.

The first article in this series was the default WeatherForecast model that is created by default in a .NET Web API project. We'll build off Article 1 to start reading in values from environment variables and appsettings.json files.

The code for this article can be found in the following GitHub Repo - Article 2. The repository will contain a dedicated directory for each article in the series.

Environment Variables

Environment variables are used for specifying external configurations or settings such as credentials, secrets, service configs, and any important stuff we need to remember. Not just are they important but they can change from time to time, so they need to be in a location for quick access to change and be available for any resource or application to pick up these changes.

First, let's review how we set environment variables on macOS or similar *nix environments. Read my short article on creating Environment Variables as a refresher.

Now let's review how to read those environment variables in a .NET Web API project.

Read Runtime Environment in .NET

One of the primary reasons to read an environment variable is to identify the correct environment your application/ service is running in. Visual Studio, on both PC and Mac, has a built-in Environment Variable Configuration feature built into the IDE.

We can set any value we'd like to use in our application by using the .NET Web API project's properties. Right-click the main project in the Visual Studio Solution Explorer and select Properties. In the Properties window, Go to the Run > Configurations > Default section. You'll see the Environment Variables table.

The example project we built in Article-1 is setting the ASPNETCORE_ENVIRONMENT variable to the value Development. The ASPNETCORE_ENVIRONMENT is a reserved word for .NET to automatically assign it to the application's Hosting Environment. You can read further detail about .NET Runtime Environments here.

Back to the code: the Program.cs file is using the ASPNETCORE_ENVIRONMENT variable to determine if the environment is set to Development. The if statement on line 38 will determine if the Swagger (OpenAPI) Documentation should be displayed. In the screenshot below I'm running the project and set a breakpoint on line 19. I'm hovering over the app.Environment variable. As you can see .NET read in the value and the EnvironmentName is set to Development.

Read Environment Variables in .NET

Now let's review custom environment variables, I'm going to create a new env variable VS_ENV in the Visual Studio properties window and one env variable MACOS_ENV in macOS (.zshrc file). If you are using bash, it would be created in your .bashrc file. Below are screenshots of the newly created env variables.

⚠️ WARNING! ⚠️

Visual Studio won't read in your MACOS (export env variables) by default. In order to have Visual Studio read in OS env variables you need to start Visual Studio from your terminal. You can't double click the icon. Shut down your current instance of Visual Studio and start the application from your terminal.

To start Visual Studio from your terminal use the following command in your terminal:

open -n "/Applications/Visual Studio.app"

Now back to work, add the following code to your Program.cs file to read our new env variables values.

// Taken from Program.cs
...

var app = builder.Build();

var vs_env = Environment.GetEnvironmentVariable("VS_ENV"));
var macos_env = Environment.GetEnvironmentVariable("MAC_ENV"));

var dict = Environment.GetEnvironmentVariables();
//Add Breakpoint on next line
foreach(var d in dict)
{
    Console.WriteLine(d);
}

...

Add a breakpoint stopping on the foreach statement and run the project. On start-up, hover over the dict variable and you'll see all environment variables that are read in from Visual Studio. You can hover over the vs_env and macos_env variables and see the values we created. Cool, we can read env variables now.

Starting Visual Studio on your Mac from the terminal is not something you want to do each time you start the app. For that reason, I stick to using environment variables from either the project's properties windows we used earlier or I use the project's appsettings.json files. These files can be set to use a runtime environment automatically. Based on the ASPNETCORE_ENVIRONMENT variable, .NET will load the matching appsettings.json file. Let's test it.

Read appsettings.json Variables in .NET

In .NET 6, the WebApplicationBuilder class exposes the Configuration properties to the application. The Configuration class makes it easy to read values from the appsettings.{RuntimeEnvironment}.json files.

Let's create a new file at the application root of the project named: appsettings.staging.json. Visual Studio will automatically nest app settings environment files under the main appsettings.json file.

The app setting files should have the following content:

// appsettings.Development.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "MyENV": "ImFromDevelopment"
}



// appsettings.Staging.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "MyENV": "ImFromStaging"
}

In the Program.cs file we'll add two lines of code to read the configuration value MyENV. Below is what your Program.cs files should look like. Values from the appsettings.json files can be read in multiple ways. The first new line of code is using square bracket notation and the second new line of code is using the GetValue<Type> method to read the same value.

We will run this project two times. One time with the Visual Studio environment variable ASPNETCORE_ENVIRONMENT=Development and another run with the environment variable ASPNETCORE_ENVIRONMENT=Staging. The screenshot below shows the values read from each runtime environment.

There you have it, Visual Studio will load the correct appsettings.json file based on your ASPNETCORE_ENVIRONMENT variable automatically. This is great for local development and you can write to the app setting files via CI/CD builds and deploy builds with the correct variables based on the runtime environment.

Strongly Typed Settings - Options Pattern

Well now use the Options Pattern to provide the variable/config/setting values from the appsettings.json file into a class structure that can be utilized throughout your application.

// Updated appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "SampleClass": {
    "StringValue": "String Sample",
    "BooleanValue": true
  }
}

We'll create the SampleClass.cs as shown below.

// New file, SampleClass.cs

using System;
namespace article_2_environment_variables;

public class SampleClass
{
    public string StringValue { get; set; }
    public bool BooleanValue { get; set; }
}

Next, add a single line in the Program.cs file to bind the values from the JSON file to the class object. That's it.

// Program.cs File

...

builder.Services.Configure<SampleClass>(builder.Configuration.GetSection(nameof(SampleClass)));

...

You can now use Dependency Injection (DI) to use these values in your WeatherForecastController. Setup your class object in the controller's constructor as below. DI is a recommended approach instead of global/ static variables.

// WeatherForecastController.cs

...

private readonly SampleClass _sampleClass;

public WeatherForecastController(ILogger<WeatherForecastController> logger, IOptions<SampleClass> sampleClassOptions)
{
    _logger = logger;
    _sampleClass = sampleClassOptions.Value;
}

 [HttpGet]
 [Route("SampleClass")]
 public SampleClass GetSampleClass()
 {
    return _sampleClass;
 }

...

When running the project (set ASPNETCORE_ENVIRONMENT=Development you can now hit this new /SampleClass endpoint and see the values returned from your API.

End

The official .NET docs are great. Read further details here.

This article is the start of a series on how to build an API using the .NET Framework. I'm sticking with .NET 6, it is the latest Long-Term-Support (LTS) Version.

I'll be using Visual Studio for Mac as my IDE. Before you start yelling, I love VS Code too, I use it for everything other than .NET Web API development. The built-in dev web server, class/ controller file generation, project generation, etc. is just a simpler and faster experience than hand typing everything via terminal. Don't hate. Moving on.

Environment

This walkthrough will be built on macOS. However, no reason you can't follow along on Windows as well.

The code for this article can be found in the following GitHub Repo. The repository will contain a dedicated directory for each article in the series.

Tools

• Visual Studio for Mac

  • As of March 2023, installing Visual Studio for Mac will also install the .NET 7 SDK, which is not LTS. So we'll manually download and install the [.NET 6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) to use on this walkthrough.

• macOS

Creating Project

Let's get started creating our project.

Start up Visual Studio for Mac and select the New project button.

We'll choose the "Web and Console" > "App" category and select the API (C#) template and click Continue.

The next step of the project wizard will prompt you to select the Target framework. Again, we're sticking with .NET 6.0. For the Advanced settings, we'll select the following options:

• No need for HTTPS for this walkthrough.

• Enable the use of controllers. We'll explore the Minimal API design approach in later articles.

• Enable OpenAPI support. We'll use the UI-based OpenAPI spec AKA Swagger documentation tool.

• Enable top-level Statements. I also build in Python from time to time, so the fewer brackets the better. This is a recent feature available in C#10.

Click continue to move on.

Choose your local directory for the project and leave the project in a subfolder to keep it organized.

Click Create.

Running the Project

The default project will include an example WeatherForecast.cs class and the WeatherForecastController.cs controller file.

You should see a window with the directory structure looking just like the image below. Click the Play icon in the toolbar to run the default project.

Starting up the project will do the following:

• Load all dependencies listed in the Dependencies folder, specifically Nuget, the .NET package manager.

• Once all packages are downloaded Visual Studio will build the project producing compiled executable files to run.

Visual Studio will start up your default browser using the applicationUrl specified in your launchSettings.json file. The JSON code below is a sample of my project. The application started up automatically using the URL: http://localhost:5084 and added the launch path: swagger to automatically load the OpenAPI (Swagger) web page.

...
// Sample from Properties > launchSettings.json 

...

  "profiles": {
    "article_1_getting_started": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "http://localhost:5084",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

...

The Swagger UI tool is building an XML file based on the OpenAPI specifications interpreted in your project. You can run the example WeatherForecast endpoint via the UI or copy the CURL statement if you want to hit the endpoint from your terminal.

That's all for now, getting started with a .NET 6 Web API project. Click the square icon (where the play button was) in the Visual Studio toolbar to quit the project.

Future articles in this series will cover further configurations regarding security, database connections, and more.

This article will setup a basic Hello World FastAPI project running in Docker. The purpose is to start off small before starting on a full real world project.

What and Why

Docker is a containerization platform. Docker combines application source code and dependencies so you can run your code in any environment. The container engine runs directly on your Operating System, so containers can be scaled directly on your host... assuming it can handle the compute and storage load.

There are so many resources for Docker, including Docker's home site. No quick and easy way to learn Docker. If you need a further deep dive take a look at Docker's Getting Started pages.

You can also follow our SQL Server on macOS using Docker article to get Docker Desktop installed if you don't have it already.

Code Repo

Code for this article can be found in the following GitHub Repo - Article 5.

Setup FastAPI

The API code is a simple example for now. Our focus is on the detail of the DockerFile and configuration.

Our FastAPI project will only have one route/ endpoint to return Hello World.

# app.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return { "message": "Hello world" }

Our python requirements.txt file only includes the basics, FastAPI and our web server, Uvicorn:

fastapi>=0.68.0,<0.69.0
uvicorn>=0.15.0,<0.16.0

Setup Docker

# Using Python 3.9 
FROM python:3.9

# Setup working directory
RUN mkdir code
WORKDIR /code

# Copy requirements file to our working directory
COPY ./requirements.txt /code/requirements.txt

# Install packages - Use cache dependencies 
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt

# Copy our code over to our working directory
COPY ./ /code/app

# Run our project exposed on port 80
CMD ["uvicorn", "app.app:app", "--host", "0.0.0.0", "--port", "80"]

Now let's start decoding the DockerFile.

FROM

This statement is your starting command which initializes a new build and sets the base image that your environment will be working with. A Dockerfile has to start with a FROM statement.

Containers work in a layered environment, so picture this as your most fundamental dev layer of your container.

In our example, we're specifying that we're using the Python3.9 image. The image is pulled from the default Docker registry where sharable images are hosted. The default registry is used when the registry URL is not specified.

WORKDIR

The next step is setting the container image's working directory. The default value is / but it is best practice to set a working directory. In our example, we're creating a directory in our image and setting our working directory to: /code.

COPY and RUN Dependencies

The Copy statement is straight forward, we're just copying our local file into our working directory or to any other directory in our Docker container image.

We're following best practice to copy the requirements.txt file first before the rest of our project files, let me explain why. The reason we're only working with dependencies is back to the fact that Docker builds images in layers. This package dependency layer is usually not changed very often so Docker will cache this layer and avoid re-running the installation of all dependencies each build.

The pip install command is executed next by the RUN command. Pip is updated and then installs requirements with the --no-cache-dir feature used. We don't need pip to cache its dependency installations, we'll let Docker be in charge of that. The install will run the installation of dependencies the first time, then every next image build if no new packages are included or changed in the requirement.txt file then Docker will reuse the cached version.

COPY App

Now copying the application source files are at the end of the Dockerfile. These files tend to change often so this layer will create itself each time when copying over application files into our container's working directory.

CMD

The final step will execute the application. We're working with the commands that we normally start a FastAPI project with but now in the form of comma separated parameters. We're executing the app object in the app file on localhost port 80.

Build Image

Now that we know what's going on in our Dockerfile, we use a specific command to build an image using the file. The command below will build our image. The -t argument will specify the name of our image.

docker build -t fastdockerimage .

The first time you build your image a long list of installation steps are are shown.

The next time, cached layers are used and you notice a much faster build time. The cached layers are used. The lengthy python downloads are avoided. The cached lines are shown in the screenshot below.

RUN Container

If you're using Docker Desktop, you can see your newly created image as shown below.

With our new Docker image we can now create and run a Docker Container.

docker run -d --name fastdockercontainer -p 80:80 fastdockerimage

We're running the container and specifying the container name as fastdockercontainer running on exposed port 80 (mapped to the internal container port 80) from on our new image called fastdockerimage. The -d argument indicates detached mode, so you can close your terminal and the terminal will still run. The Container ID is also printed to the terminal.

Docker desktop now shows our running container.

We can hit the container on localhost port 80 as usual. The application is not just running on a local Uvicorn server on our OS but in fact running on an isolated container environment.

This article was meant to clarify the basics of running a FastAPI project in Docker. Future articles will build on these foundational steps to build a real world production level project.

This article will continue our journey and connect a FastAPI project to a SQL Server database. We'll walk through a full CRUD (Create, Read, Update, Delete) example of saving data through our FastAPI project to a database. We'll work with a healthcare example and manage a Patient table. Of course, we aren't reviewing database design, so we are working with a single table for now. You should already be familiar with databases and have sufficient access required to create tables and read and insert from a database.

Code for this example can be found here - API SQL Server DB CRUD Repo. The README provides startup steps.

For this article, I'm working with a local SQL Server 2017 Database on my mac. Before continuing, if you don't have a SQL Server playground follow my article to set up SQL Server on your mac. This will give you a fully functioning SQL Server Database running in a Docker container on your local machine.

We'll also be using SQL Alchemy as the database ORM. SQL Alchemy is a well-known ORM project to connect SQL databases.

Toolkit

• FastAPI - SQL Databases
• SQL Alchemy ORM 1.4
• PyMsSql
• Pydantic Schemas/ Models
• SQL Server 2017
• Docker Desktop

Database Setup

At this point, you should already have a SQL Server Db to work with. In the project repository, run the Db_Scripts/SEED_Script.sql file to create the Patient Table and add a single record to it. Running a SELECT statement shows the single record in the table. My database is named MyTestDb, change any of the SQL Statements to make your database name when necessary.

FastAPI Db Connection

Using SQL Alchemy, we need a connection.py file to setup a database connection. We'll create this connection as a dependency to use in our API routers.

First things first, when using SQL Alchemy an engine is required to make connections to databases.

Once the engine is created, we use SQL Alchemy's sessionmaker to create a session. The session serves as a collection of queries/ statements that we call to execute in the database. The session will hold these events until the session is instructed to either commit or rollback the events.

When making a database call in our API, we call a method get_db to execute the following try/catch statement to start a database session. Once we execute our queries/ instructions in this session, the finally statement will also close the session when it is complete.

# taken from utils/connection.py

...

# Create engine
engine = create_engine(f'mssql+pymssql://{settings.DB_UID}:{settings.DB_PWD}@{settings.DB_SERVER}:{settings.DB_PORT}/{settings.DB_NAME}')

# Create Session
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)


...


try:
    db = SessionLocal()
    yield db
finally:
    db.close()

To use these database sessions, we'll import our utils module into the app.py file.

# app.py
import utils

In our API Endpoints, we insert the database connection as a dependency in the method parameter. We now have the db instance to call database instructions.

# app.py

# CRUD Routes
# GET ALL
# Response will be a LIST of schema.Patient
# The Schema.Patient List instance will be mapped from the model.Patient ORM instance from Sql Alchemy
@app.get("/Patient", response_model=List[schema.Patient])
async def GetAll(db: Session = Depends(utils.get_db)):

    # get the model.patient with the given id
    # using sql alchemy orm, we're querying the Patient table
    query = db.query(model.Patient)
    patients = query.all()

    return patients

Now have connectivity to our database, we need to discuss creating Models to interact with our database.

Models Vs Schemas

ORM Models SQL Alchemy

We're utilizing two different representations of our Patient table in the API, an ORM Model (SQL Alchemy) and a Schema Model (Pydantic).

The ORM Model is a SQL Alchemy representation of the Patient Table. This ORM model knows the database table that queries are going to be executed on by the __tablename__= 'Patient' statement. The ORM model has a direct representation of the database table fields. This assists with validation when trying to save or edit Patient fields.

ORM Models are made from the Delcarative Base SQL Alchemy Class in the utils/connection.py file. The code to create an ORM model is shown below.

# Patient/model.py

from sqlalchemy import Column, Integer, String, DateTime
from utils.connection import Base

# Base is coming from the SQL Alchemy Base class created in utils/connection.py
class Patient(Base):
    __tablename__ = 'Patient'

    ID = Column(Integer, primary_key=True)
    BirthDate = Column(DateTime)
    FirstName = Column(String(50))
    LastName = Column(String(50))
    AccountNumber = Column(String(25))
    Department = Column(String(20))
    Room = Column(String(1))

Schema Models (Pydantic)

The Schema models on the other hand are Pydantic models that can be used in the API to also:

• validate data
• identify endpoint response types
• be used in the Swagger or Redoc Documentation pages

The Schemas are created from the Pydantic BaseModel class, unlike the ORM Models.

Our Patient table has two schemas. The PatientCreate schema is used as the body request when inserting a new record in our post endpoint. The ID field is not part of this schema so the API can only validate only the required fields.

The second schema is the same representation of the Patient ORM model. Type schema has the orm_mode value set to true in order to support mapping this schema to the Patient ORM Model when returning model types. This is specifically used when we get a Patient or Patient list in our endpoints. We're using the ORM SQL Alchemy model to return the records from the database. The data is then validated and returned in the API as a Pydantic model. This is shown in the endpoint decorater:

@app.get("/Patient", response_model=List[schema.  Patient])

from datetime import datetime
from pydantic import BaseModel

# Create Patient Schema (Pydantic Model)

class PatientCreate(BaseModel):
    BirthDate: datetime
    FirstName: str
    LastName: str
    AccountNumber: str
    Department: str
    Room: str

class Patient(BaseModel):
    ID: int
    BirthDate: datetime
    FirstName: str
    LastName: str
    AccountNumber: str
    Department: str
    Room: str

    # ORM Mode is used to support models that map to ORM objects, in this case model.Patient (sqlAlchemy)
    class Config:
        orm_mode = True

Schemas can be used in different scenarios when validating or specifying only specific elements of a class object.

CRUD

Get All - READ

This endpoint will return all Patient records. No request parameters are included in this endpoint. Fast API identifies the get method by the decorator @app.get command.

The route is /Patient and the response is a list of the schema.Patient model.

# app.py

# GET ALL
# Response will be a LIST of schema.Patient
# The Schema.Patient List instance will be mapped from the model.Patient ORM instance from Sql Alchemy
@app.get("/Patient", response_model=List[schema.Patient])
async def GetAll(db: Session = Depends(utils.get_db)):

    # get the model.patient with the given id
    # using sql alchemy orm, we're querying the Patient table
    query = db.query(model.Patient)
    patients = query.all()

    return patients

Get Single - READ

This endpoint will return a single Patient record. A single ID parameter is included in this endpoint.

The route is /Patient/{ID} and the response is a single record of the schema.Patient model.

If a Patient with the provided ID is not found a 404, not found response is returned.

# app.py

# GET Single
# Response will be a single schema.Patient 
# The Schema.Patient instance will be mapped from the model.Patient ORM instance from Sql Alchemy
@app.get("/Patient/{ID}")
async def GetSingle(ID: int, db: Session = Depends(utils.get_db)):

    # get the patient with the given Patient ID
    query = db.query(model.Patient).filter(model.Patient.ID == ID)
    patient = query.one_or_none()

    if not patient:
        raise HTTPException(status_code=404, detail=f"Patient with ID {ID} not found")

    return patient

Post - Write

This endpoint will insert a single Patient record. A request body in JSON format is included in this endpoint. The request body will need to match the PatientCreate schema specified in the method parameter.

The route is /Patient and the response is a single record of the Patient model that was just inserted into the database.

After the commit command a refresh command is called. This returns the Patient model with the newly generated Patient ID. The response will now include the Patient ID which is the primary key value of the Patient.

# app.py

# POST
# Response will be a single schema.Patient after creation in the DB
# The Schema.Patient instance will be mapped from the model.Patient ORM instance from Sql Alchemy
@app.post("/Patient", response_model=schema.Patient)
async def Post(patient: schema.PatientCreate, db: Session = Depends(utils.get_db)):

    # create an instance of the model.Patient ORM model from the schema.Patient instance from the request body
    new_patient = model.Patient(BirthDate = patient.BirthDate
                            , FirstName = patient.FirstName
                            , LastName = patient.LastName
                            , AccountNumber = patient.AccountNumber
                            , Department = patient.Department
                            , Room = patient.Room)

    # add it to the session and commit it
    db.add(new_patient)
    db.commit()

    # update the patient instance to get the newly created Id
    db.refresh(new_patient) 

    # return the patient
    return new_patient

Put - Write

This endpoint will update a single Patient record. A request body in JSON format is included in this endpoint. The request body will need to match the PatientCreate schema specified in the method parameter.

The route is /Patient/{ID} and the response is a single record of the Patient model that was just updated into the database.

A query for the Patient ID is the first step to getting the existing Patient. Once found, fields are updated based on the request body schema.PatientCreate model. After the commit statement a refresh command is called. This returns the Patient model with the newly updated Patient fields.

If a Patient with the provided ID is not found a 404, not found response is returned.

# app.py

# PUT
# Response will be a single schema.Patient after creation in the DB
# The Schema.Patient instance will be mapped from the model.Patient ORM instance from Sql Alchemy
@app.put("/Patient/{ID}", response_model=schema.Patient)
async def Put(ID: int, patientUpdate: schema.Patient, db: Session = Depends(utils.get_db)):

    # get the model.Patient with the given id
    patient = db.get(model.Patient, ID)

    # update patient with the patient from request body (if patient with the given id was found)
    if patient:
        patient.BirthDate = patientUpdate.BirthDate
        patient.FirstName = patientUpdate.FirstName
        patient.LastName = patientUpdate.LastName
        patient.AccountNumber = patientUpdate.AccountNumber
        patient.Department = patientUpdate.Department
        patient.Room = patientUpdate.Room

        db.commit()
        db.refresh(patient)

    # check if patient with given id exists. If not, raise exception and return 404 not found response
    if not patient:
        raise HTTPException(status_code=404, detail=f"Patient with ID {ID} not found")

    return patient

Delete - Write

This endpoint will delete a single Patient record. A single ID parameter is included in this endpoint.

The route is /Patient/{ID} and the response a 204, No Content upon completion with no errors.

# app.py

# DELETE
@app.delete("/Patient/{ID}", status_code=status.HTTP_204_NO_CONTENT)
async def Delete(ID: int,  db: Session = Depends(utils.get_db)):

    # get the model.Patient with the given id
    patient = db.get(model.Patient, ID)

    # check if patient with given id exists and call delete
    if patient:
        db.delete(patient)
        db.commit()

End

This article reviewed the steps to set up a SQL Alchemy connection to a SQL Server database.

This simple CRUD API project shows the steps to read and write data from a SQL Server database table for persistent storage.

If you haven't seen Microsoft's latest Docs site update, you really should check them out. There is a getting started article regarding SQL Server (2017) Containers on Linux and other OSs including Azure. The SQL Server 2019 version article is also available. This post will go over the detailed steps on setting up a locally running SQL Server (2017) instance on your macOS.

Step 1: Installing Docker

(If you have Docker already installed skip to step 2)

Hopefully, you have a working knowledge of Docker. If you don't, let's walk through the steps of setting up a Docker Desktop for Mac. Download the install from the Docker Store.

Based on your chip either Intel or Apple M, download the appropriate .dmg file. Once downloaded, start the .dmg file and drop the file into your Applications folder to install it.

Start Docker from your Application folder. You may need to enter your password for elevated privileges. Accept the Service Agreement to continue.

Configure Docker Preferences

Once Docker is running you'll see the while icon in your toolbar.

Microsoft's original article I linked in the intro specifies system preferences as the following:

• Docker Engine 1.8+
• Minimum of 2 GB of disk space
  • (Common sense sense says you'll disk space will increase with the size of your DB.....)
• Minimum of 2 GB of RAM
  • (I prefer to extend to 4GB if you'll be using this heavily in testing and supporting other local apps)

FYI: Any system resource changes will require a Docker Restart.

Step 2: Setup the SQL Container

At this point, Docker is installed. If it isn't running already, double click the Docker App Icon in the Applications folder.

You will see the Docker whale icon in the toolbar. Click on the whale icon and open the dashboard. A fresh install will have no containers listed. The green box in the bottom right will indicate your Docker engine is running.

With Docker running, let's open a terminal window to execute the next series of commands.

We will pull down the SQL Server container image from the Docker Hub with the following command:

# pull image

docker pull mcr.microsoft.com/mssql/server:2017-latest

Now we need to run the container to set up the SQL Server instance.

Remember the back slashes below indicate a new line or else you can just type this all on one line without the backslashes.

sudo docker run -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=MyPassword1' \
   -p 1433:1433 --name LocalSqlServer \
   -d mcr.microsoft.com/mssql/server:2017-latest

The command above uses the following flags:

The command will now run the SQL Server container. Your Docker dashboard will now list the new container with the name you specified in the --name flag.

From your terminal, the command docker container ls will list the containers in your Docker instance. You can see that the name you specified in the command statement is now listed in your terminal as well..

Step 3: Connecting to SQL Server

The database container has been created but we need to get into the container and create our new database.

Connect via Command Line

Connect to the container:

docker exec -it LocalSqlServer "bash"

Once in the container, you'll have a :/# prompt.

Now we can connect to the SQL Instance:

/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'MyPassword1'

You can leave out the -P flag and you will be prompted for the password. Once connected to the SQL instance, you will now have the 1> prompt. A simple SELECT 1+1 will return the following:

A simple script in the SQLCMD prompt can be tested with the prompt above. From within the SQLCMD prompt, you can feed any T-SQL statement followed by the GO statement to run the command.

Next steps are to list existing databases. You will see the default SQL Server databases. We'll create a new DB and than show the newly create MyTestDB show in the database list.

Connect Using Azure Data Studio

You can download Azure Data Studio for macOS to connect to your new SQL Server Database.

Enter the information below, localhost as your server. Use SA as your login until you get a new user created and use the default password specified earlier.

You now have a GUI to now interact with, you see our new DB listed below.

Start and stop the Docker container as you please, when you want to work with SQL Server on your Mac!

End

If you followed along with this walkthrough, you:

• Downloaded and Setup Docker Desktop for Mac
• Pulled the SQL Server 2017 Image
• Ran and initialized a new SQL Server Database Instance
• Connected to the new Docker container and SQL Server Command Prompt to interact with the SQL Server Database

Reference Links

• MS Docs
• MS Docs SQL Server on Linux

The previous article reviewed how to set and read environment variables. We'll use that knowledge and set up an API Key as an environment variable for authorization in a FastAPI project. Keys are not a variable you want to check into your code repo, so environment variables are a perfect place for them.

An API Key serves two main purposes, a method of identifying the caller or requestor of the API Service if you're assigning keys and also controlling access to the API Service. It is a simple method of security to protect API resources.

Code for this example can be found here - API Key Project Repo. The README provides startup steps.

Setup an API Key Environment Variable

For this walkthrough, we will store the API Key in a .env file.

# .env file

API_KEY="my file key"

API Key Middleware

FastAPI will require some middleware in order to process the key and validate it. We'll create a new file auth.py to host the key validation middleware. Let's review the imports in the file.

First off, we're importing the class Settings() and get_settings method which will serve as a cache. These are dependencies for our environment variables. The cache will hold the environment variables read from our .env file.

Additional FastAPI imports are required, APIKeyHeader and Security in order to validate API Keys coming in through the header. The Depends function will load our dependencies like the Settings() cache for our API Key.

The starlette and HTTP Exception imports are used to return forbidden responses and statuses when the API Key is invalid or not included.

# Imports in auth.py file

from config import Settings, get_settings

from fastapi.security.api_key import APIKeyHeader
from fastapi import Security, HTTPException, Depends
from starlette.status import HTTP_403_FORBIDDEN

To utilize the API Key, the caller or requestor will be required to include the API Key in the Request Header. The API Key will need to be included in the header for all secure requests in our API. The header name, as shown below, is named access_token.

api_key_header = APIKeyHeader(name="access_token", auto_error=False)

The next step is the validation process. When the header is not included or is invalid, then a 403 status is returned with the message: Could not validate API Key.

Valid API Key requests are forwarded to the original route.

async def get_api_key(api_key_header: str = Security(api_key_header)):
    if api_key_header == config_env["API_KEY"]:
        return api_key_header   
    else:
        raise HTTPException(
            status_code=HTTP_403_FORBIDDEN, detail="Could not validate API KEY"
        )

The entire middleware code is shown below:

# auth.py

from .config import config_env
from fastapi.security.api_key import APIKeyHeader
from fastapi import Security, HTTPException
from starlette.status import HTTP_403_FORBIDDEN

api_key_header = APIKeyHeader(name="access_token", auto_error=False)

async def get_api_key(api_key_header: str = Security(api_key_header)):
    if api_key_header == config_env["API_KEY"]:
        return api_key_header   
    else:
        raise HTTPException(
            status_code=HTTP_403_FORBIDDEN, detail="Could not validate API KEY"
        )

Lock Down Routes

The app.py file will require two new imports to secure the API endpoints. We are importing the APIKey class and auth utility file we created.

# New Imports for app.py
from fastapi.security.api_key import APIKey
import auth

To utilize this middleware in our API, we will assign an API Key dependency to secure our routes. We will include the validation step as a parameter in our routes method. The API Key middleware is a dependency call to auth.get_api_key that is executed before executing the endpoint.

The first route listed below is using the API Key dependency in its route method. Before executing the endpoint, the API Key validation step is performed. If it does not pass this validation sequence, the 403 response is returned. If the API Key validation is successful, the route endpoint will execute and return the JSON body shown below.

The second route in the example is not locked down. The route can be executed without providing an API Key.

# Routes in the app.py file

# Lockedown Route
@app.get("/secure")
async def info(api_key: APIKey = Depends(auth.get_api_key)):
    return {
        "default variable": api_key
    }

# Open Route
@app.get("/open")
async def info():
    return {
        "default variable": "Open Route"
    }

Using API Key in Swagger

With the code updates complete, let's see how this works in Swagger.

Start up the server.

uvicorn app:app --reload

Swagger now has two new UI features.

1. The two default routes are listed, only one has the lock icon assigned. The /secure route will require an API Key to be provided and validated before returning API resources.
   If you execute the route without providing a valid API Key you will be denied access. In the screenshot below, no API Key was included in the header request and a 403 Forbidden response was returned.

   

2. The green Authorize button is the next new feature. You can click on this to enter your secret API Key. This key will now be sent as a header to your API for validation with each request.
   Enter your API Key exactly as it exists in your .env file.
   Click Authorize and close the window.

   

   If you re-execute the route now that you entered your API Key, you will receive a successful response and see that your API Key was included in the request's header.

   

End

You now have a working API Key Middleware setup for a FastAPI Project. This example was using a plaintext key but additional steps to "productionize" would be to encrypt the key and add a step to decrypt the key in your auth.py utility file. HTTPS must always be enforced when dealing with keys being sent over the wire.

Individual User Auth can also be applied by utilizing JWT and will be covered in later articles.

Recap... the first article gave a simple Hello World setup to get FastAPI up and running. This article will take the next step and introduce using environment variables in your FastAPI project.

Environment Variables

Environment variables are used for specifying external configurations or settings such as: credentials, secrets, important stuff we need to remember, etc. Not just are they important but they can change from time to time, so they need to be in a location for quick access to change and be available for any resource or application that is utilizing them.

First, let's review how we set environment variables on macOS or similar *nix environments. Read my short article on Environment Variables as a refresher.

Now let's review how to read those environment variables in a FastAPI project.

Read Environment Variables in FastAPI

Reading environment variables can be done with the os and the dotenv libraries to read both system or file-based variables. It is more or less a default common practice in Python development. The example below shows how this is done.

import os
from dotenv import dotenv_values

# Python Environment Variable setup required on System or .env file
config_env = {
    **dotenv_values(".env"),  # load local file development variables
    **os.environ,  # override loaded values with system environment variables
}

# Access the variable like below
# print(config_env["VAR_NAME"])

This is a fine option but not the best option when working with FastAPI.

Let's review how to do this the FastAPI way according to the documentation.

Option 1 - Pyndatic Settings()

Code for this example can be found here- Default Option. The README provides startup steps.

Utilizing the Pydantic Settings Management utility is the recommended option when working with environment variables in a FastAPI project. This option will walk through creating a global class instance of your environment variables to be shared in your FastAPI project.

This is done by importing Pydantic's BaseSettings and creating a class Settings() just as with any Pydantic model.

We'll follow good standards and create a config file to host our environment variable settings rather than having this clutter up the main app.py file. When the Settings() class is instantiated, Pydantic will read in the environment variables (case sensitive) for each of the attributes you created in your class.

Default values will be supplied to the class instance if the environment variables do not exist.

Caution when using default values if you are trying to avoid checking in sensitive information in your code repository.

# config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    DEFAULT_VAR="some default string value"  # default value if env variable does not exist
    API_KEY: str
    APP_MAX: int=100 # default value if env variable does not exist

# global instance
settings = Settings()

With the config in a separate file, you can import it into your main app.py file.

In our example the route /vars will return the class attributes that were imported.

# app.py
from fastapi import FastAPI

# import settings for variable access
from config import settings

app = FastAPI()

@app.get("/vars")
async def info():
    return {
        "default variable": settings.DEFAULT_VAR,
        "api key": settings.API_KEY,
        "app max integer": settings.APP_MAX,
    }

I created my python virtual environment and started the server by including the environment variables at invocation. The API_KEY and APP_MAX are set at invocation but the DEFAULT_VAR will be the default value set up in the Pydantic class because I am not specifying a value for it. Hitting the API will provide the result below:

# Response body for /vars
{
  "default variable": "some default string value",
  "api key": "SECRETKEY",
  "app max integer": 799
}

Option 2 - Environment Variables using LRU Cache

You can follow along with the following GitHub Project - Cache Option. The README provides startup steps.

Instead of creating a global settings instance, another way of reading environment variables is to utilize LRU (Least Recently Used) Cache. This creates a dependency of Settings() instead of a default instance of settings=Settings(). For this option, more imports are required: LRU Cache, Depends, and the class Settings(). Note, that the Settings() class is imported not the instance settings, the global instance is no longer needed for this option.

# import 
from functools import lru_cache

from fastapi import Depends, FastAPI

from config import Settings

app = FastAPI()

# New decorator for cache
@lru_cache()
def get_settings():
    return Settings()

# route is now using the Depends feature to import Settings
@app.get("/vars")
async def info(settings: Settings = Depends(get_settings)):
    return {
        "default variable": settings.DEFAULT_VAR,
        "api key": settings.API_KEY,
        "app max integer": settings.APP_MAX,
    }

The config.py file change for this option is just removing the created class instance (last line from the option 1). Everything else is the same.

# Updated config.py file
from pydantic import BaseSettings

class Settings(BaseSettings):
    DEFAULT_VAR="some default string value" # default value if env variable does not exist
    API_KEY: str
    APP_MAX: int=100 # default value if env variable does not exist

I'm starting the virtual environment and server by including the environment variables at invocation just like before.

# Response body for /vars
{
  "default variable": "some default string value",
  "api key": "SECRETKEY",
  "app max integer": 799
}

Option 3 - Environment Variables in .env File

You can follow along with the following GitHub Project - Env File Option. The README provides startup steps.

The last thing we'll cover is to set up environment variables in a local .env file instead of passing them during invocation. I prefer using env files that I can leave in a project.

# Example .env file
API_KEY="my file key"
APP_MAX="199"

REMEMBER: Add the .env file to your .gitignore file so it won't be checked into your repository.

Your new .env file is added to the config.py file as part of the class attributes.

# config.py
from pydantic import BaseSettings


class Settings(BaseSettings):
    DEFAULT_VAR="some default string value" # default value if env variable does not exist
    API_KEY: str
    APP_MAX: int=100 # default value if env variable does not exist

# specify .env file location as Config attribute
    class Config:
        env_file = ".env.sample"

Pydantic will now look explicitly in your file to read in environment variables. I'm starting the virtual environment and server now with the following command.

# Response body for /vars
{
  "default variable": "some default string value",
  "api key": "my file key",
  "app max integer": 199
}

End

The official FastAPI docs are great and explain in further detail the use of LRU Cache and other options around Environment Variables and Settings. Read them here.

In the next article, we'll review API Key authorization.

This article is meant as a reminder on how to set up and read environment variables for development.

• Python Program Invocation. This option allows for variables to live for the duration of your program. This works when starting any Python program regardless of the operating system.

  # Startup with env variables during program invocation
  SOME_KEY="qwerty123" SOME_PORT="99999" myPythonApp.py
  

• Set via terminal with the EXPORT command. Environment variables created in your terminal are saved to your terminals session. They only exist for the duration of your terminal window, once closed they are gone and are not available across multiple terminal windows. The screenshot below shows an example of a newly created environment variable SOME_TEXT_VAR created in one session that is not available in another.

• Using a .env file in development project.
  Add a dot env file to your project to store variables for your project. Depending on your project you can read in the environment variables in different ways specific to your project.

• Create permanent environment variables by modifying your Bash or ZSH (Z) Shell Profiles. Based on whatever terminal you use, open the following (macOS) ~/.bash-profile (bash) or ~/.zshrc (ZSH) file in order to create permanent environment variables. You can open those files in nano, vi, or whatever text editor of your liking. The # is a comment indicator. The example below is shown using the ZSH shell in my terminal.

Read Environment Variables

From your terminal, you can print out a single environment variable at a time or all of them at once.

echo $VAR_NAME
# terminal print single variable

printenv
# print all system environment variables

End

These are helpful reminders when setting up and accessing environment variables for development.

This article is the start of a series on how to build an API using the FastAPI Framework.

Environment

This walkthrough will be built on macOS. However, no reason you can't follow along on Windows as well. I'll try to provide instructions for both when possible.

Code for this article can be found in the following GitHub Repo. Each folder will contain a separate project assigned to the assigned article in the series.

Tools

• Python 3
• macOS
• VS Code (Editor) with the Python Extension from Microsoft

Python Virtual Environments

Navigate to a directory of your choosing to set up your new FastAPI Project. In your new directory follow the next Command Line/ Terminal scripts.

Virtual Environments are a Python best practice to keep different project modules/ libraries separate from each other. You can use the pip freeze command to add required libraries to a requirements.txt file. This allows you to re-install the required libraries for the project at a later time.

Setup in Windows

# Create Virtual Environment
python3 -m venv venv

# Change VS Code Python Interpreter to the VENV python Version

# Start Virtual Environment
venv\Scripts\activate.bat

# Command Prompt will show running Virtual Environment

Setup in macOS

# Create Virtual Environment
python3 -m venv venv

# Change VS Code Python Interpreter to the VENV python Version

# Start Virtual Environment
source venv/bin/activate

# Command Prompt will show running Virtual Environment

Install Packages

# Install FAST API with all dependencies for now
pip install "FastAPI[all]"

Running the setup commands should look like the following screenshot. The activated Virtual Environment is shown at the start of the terminal line venv.

FastAPI Hello World Example

REF: https://fastapi.tiangolo.com/tutorial/first-steps/

Create a new file named: app.py

# app.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return { "message": "Hello world" }

Run the FastAPI Server

From your terminal or integrated terminal in VS Code, run the following commands to start the API server.

# Start up the server
# First app is the app filename
# Second app is the name of the FastAPI instance in the app.py file
# --reload is a hot reload flag for the FastAPI Server

uvicorn app:app --reload

Starting the server will show the running URL and Port.

Visit http://localhost:8000/docs to view the Swagger Documentation for the FastAPI Server. The ReDoc interface is also available by default at the following URL: http://localhost:8000/redoc.

The default endpoint in the example below / will return the Hello World payload.

The articles in this series will cover further configurations regarding security, database connections, and more.

As discussed in Part 1, a simple for loop will iterate through a sequential type value.

# Iterate through a list or string
name = "josh"
for n in name: 
        i

# OUTPUT:
# 'j'
# 'o'
# 's'
# 'h'

map()

The map() feature offers an alternative to looping through a sequence while also applying a function on each traversed element.

The example below will traverse each element in the dictionary and activate the isActive field. We pass both the function and the array.

The map() function returns an object. To print the results, we convert the resulting object back to a list using list().

Lists are reference types so the original list is also updated.

users = [{"name": "Josh", "isActive": False}
                    , {"name": "Esmeralda", "isActive": False}
                    , {"name": "Daniel", "isActive": False}]

def activate_users(usr):
        usr["isActive"] = True
        return usr

updated_users = map(activate_users, users)
users_active = list(updated_users) # convert object to list

users_active
# OUTPUT: 
# [{'name': 'Josh', 'isActive': True}
#   , {'name': 'Esmeralda', 'isActive': True}
#   , {'name': 'Daniel', 'isActive': True}]

List Comprehensions

List comprehensions offer a 'less lines of code' approach but can also get very complicated very quickly and also decrease readability.

The example below will apply the upper() function to each element in the names list.

List comprehensions return a list.

names = ["josh", "daniel", "esmeralda"]
names_upper = [name.upper() for name in names ]
names_upper

# OUTPUT:
# ['JOSH', 'DANIEL', 'ESMERALDA']

List comprehensions are composed of three main parts:

• list: a sequence collection
• element: individual element in the list
• expression: Action to apply on the element
• condition: optional condition to apply to the element

result_list = [expression for element in list]
result_list = [expression for element in list (optional) if condition]

Let's take a look at the map() example above and user a list comprehension to perform the same task. The output does not have to be converted to a list because a list comprehension's result is a list.

users = [{"name": "Josh", "isActive": False}
                    , {"name": "Esmeralda", "isActive": False}
                    , {"name": "Daniel", "isActive": False}]

def activate_users(usr):
        usr["isActive"] = True
        return usr

updated_users = [activate_users(usr) for usr in users]

updated_users
# OUTPUT: 
# [{'name': 'Josh', 'isActive': True}
#   , {'name': 'Esmeralda', 'isActive': True}
#   , {'name': 'Daniel', 'isActive': True}]

List Comprehension with Conditional

grades = [90, 89, 75, 100, 85, 95, 70]

# Filter out only a grade that is equal to or more than 90
nineties = [grade for grade in grades if grade >= 90]
nineties

# OUTPUT:
# [90, 100, 95]

# Filter out only a grade that is equal to or more than 90
nineties = [grade if grade >= 90 else 0 for grade in grades]
nineties

# OUTPUT: 
# [90, 0, 0, 100, 0, 95]

Set Comprehension

Very similar to list comprehensions but the resulting value is a set, meaning the result will not have duplicates. The format and components of set comprehensions are the same list comprehensions. Conditional statements are also optional to use in set comprehensions.

The example below removes the duplicate names from the set.

names = "josh esmeralda daniel esmeralda daniel josh".split()
names_set = { name for name in names }
names_set

# OUTPUT:
# {'daniel', 'esmeralda', 'josh'}

type(names_set)
# <class 'set'>

Dictionary Comprehension

The last example will cover dictionary comprehensions that share similar properties and functionality as set and list comprehensions. The difference being that the result is a dictionary and a key index is required.

The example below will get a list of elements from the names dictionary. For each key:value pair, the value is multiplied by 100 and a new dictionary is returned.
The original dictionary is not altered.

names = { "josh": .99, "daniel": .10, "esmeralda": .80 }

names_dict = { key:value*100 for (key, value) in names.items() }
names_dict

# OUTPUT:
# {'josh': 99.0, 'daniel': 10.0, 'esmeralda': 80.0}

type(names_dict)
# <class 'set'>

Lists

A list in python is a collection of various elements. A list can be a collection of integers, characters, dictionaries, or all of the above, not to be confused with an array. An array requires all elements to be of the same type.

# Empty List
empty_list = []

# List of integers
number_list = [1, 2, 3, 4, 5]

# List of strings
alpha_list = ["alpha", "beta", "charlie", "delta", "echo"]

# List of dictionaries
dict_list = [{"id": 1, "role": "admin"}, {"id": 2, "role": "manager"}] 

# List of mixed value types
mixed_list = [1, "two", 3, False]

# check the type
type(number_list)
# OUTPUT: <class 'list'>

Index & Length

# Access list items by a positive index
alpha_list[1]
# OUTPUT: 'beta'

# Negative index can also be used to access list elements
number_list[-2]
# OUTPUT: 4

# Length of the list
len(alpha_list)
# OUTPUT: 5

Slicing

Using indexes, access a subset of a list by using two indexes seperated by a colon [x:y], x element is inclusive, y element is not. Omitting the first index, the slice starts at index 0. Omitting the second index, the slice continues until the end of the string.

number_list[1:3]
# OUTPUT: [2, 3]

number_list[:4]
# OUTPUT: [1, 2, 3, 4]

number_list[2:]
# OUTPUT: [3, 4, 5]

# Negative indexes with slicing can also be used
number_list[-3:]
# OUTPUT: [3, 4, 5]

number_list[:-3]
# OUTPUT: [1, 2]

Join & Split

String variables can be split into a list. Default delimiter is a space but a character delimeter can be specified.

"Hello world".split()
# OUTPUT: ['Hello', 'world']

"Hello world".split('o')
# OUTPUT: ['Hell', ' w', 'rld']

# The Join method does the opposite and combines a list into a string
" ".join(['Hello', 'world'])
# OUTPUT:  'Hello world'

"-".join(['Hello', 'world'])
# OUTPUT:  'Hello-world'

Mutable

Lists are mutable.

# Add elements by appending to the end of the list
alpha_list = ["alpha", "beta"]
alpha_list.append("charlie")

alpha_list
# OUTPUT: ['alpha', 'beta', 'charlie']

#Insert elements at a specific index
alpha_list.insert(0, "delta")
alpha_list
#OUTPUT; ['delta', 'alpha', 'beta', 'charlie']

Remove/ Delete

Elements can also be removed/deleted from the list.

# del will remove the element at a specific index
del alpha_list[3]
alpha_list
#OUTPUT; ['delta', 'alpha', 'beta']

# Remove will remove the first match in the list
# If multiple matches exist in the list, not all elements are removed
alpha_list.remove('alpha')
alpha_list
#OUTPUT; ['delta', 'beta']

Other Helper Methods

# Reverse the order of the list
alpha_list = ["alpha", "beta"]
alpha_list.reverse()
alpha_list
# OUTPUT: ['beta', 'alpha']


# Sort the list
alpha_list.sort()
alpha_list
# OUTPUT; ['delta', 'beta']

For Loop

# Create a List of grades
grades = [90, 80, 95, 100, 75]

# Iterate over the list and print each individual grade
for i in grades:
        print(i)

# OUTPUT:
# 90
# 80
# 95
# 100
# 75

# Show indexes for elements in list using the enumerate function in a for loop
alpha_list = ["alpha", "beta", "charlie"]
for index, alpha  in enumerate(alpha_list):
        print(f"The word at index: {index} is {alpha} ")

# OUTPUT: 
# The word at index: 0 is alpha
# The word at index: 1 is beta
# The word at index: 2 is charlie

Part 2 of this series will include the more functional programming concepts such as map() and list comprehension examples.

Change macOS Shell to zsh, if it's not set already.

1. System Preferences
2. Select Users & Groups
3. Right click your account and Select 'Advanced Options'. If nothing is happening, you may need to click on the lock icon in the bottom left corner to allow changes.
4. Change the Login Shell options to /bin/zsh.
5. Now that the default shell is set to zsh, you can test your efforts by opening a new terminal window and enter the following: echo \$SHELL. The output should be: /bin/zsh.

Zsh is configurable by the ~/.zshrc file. OH MY ZSH is a framework for managing your zsh configurations. Let's get this installed and see up all the cool stuff.

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install iterm2 using Homebrew

brew install --cask iterm2

What is the --cask you ask?

“To install, drag this icon…” no more. Homebrew Cask installs macOS apps, fonts and plugins and other non-open source software. Read More

Install git, if you don't have it already...

brew install git

Install Oh My Zsh

The install is as easy as executing the curl statement on the website.

$ sh -c "$(curl -fsSL https://raw.github.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

With the framework installed, open the open ~/.zshrc (to open using TextEdit), code ~/.zshrc (to open using VS Code), or vim ~/.zshrc (to open using Vim) review and modify any zsh properties to your liking. I'm using the 'itsJCs-agnoster' theme: ZSH_THEME="itsJCs-agnoster".

This theme is a fork off the original 'agnoster' theme that I customized for myself. You can clone the theme project from github. The downloaded theme must be copied into the hidden .oh-my-zsh home directory in order to read it: ~/.oh-my-zsh/themes.

The catch with my theme is that it requires Powerline fonts to support the icons shown in the terminal. The following installation steps on the GitHub page will install the required fonts.

1. Clone git clone https://github.com/powerline/fonts.git --depth=1
2. Install cd fonts ./install.sh
3. Clean-up cd .. rm -rf fonts

The list of installed fonts is available on the GitHub page. I like Source Code Pro for Powerline

To activate the fonts, you'll need to change the fonts in your iTerms preferences.

Here is a list of my other custom settings:

You can export your preferences as JSON when you find the settings that suit you best:

• Profiles > Text > Font: Operator Mono Lig, 15pt, Medium
  • My font of choice, you can use any Ligature Coding font (Operator Mono, Dank Mono, etc.)
• Profiles > Text > Font: Enable 'Use Ligatures'
• Profiles > Text > Font: Enable 'Use a different font for non-ASCII Text'

• Profiles > Text > Non-ASCII Font: Source Code Pro for Powerline, 15pt, Medium

  • You will need to install a Powerline-patched font for this theme to render correctly.

• Profiles > Text > Font: Vertical Height = 100

• Profiles > Text > Font: Line Height = 100
• Profiles > Colors > Basic Colors: Foreground and Selection = #10ff00
• Profiles > Colors > Basic Colors: Background = #101010
• Profiles > Colors > Cursor Colors: Cursor Guide Enabled, set to #808080
• Profiles > Window > Window Appearance > Transparency: ~ 35-40%
• Profiles > Window > Settings for New Windows > Style: Fullscreen
• Profiles > Session > Miscellaneous: Enable 'Status Bar Enabled'
• Profiles > Session > Configure Status Bar: Add CPU, RAM, Network, Current Dir Components
• Profiles > Session > Configure Status Bar > Advanced: Background = #000000
• Appearance > General > Status Bar Location: Bottom
• General > Startup > Window Restoration Policy: Open Default Window Arrangement
  • I like a three tile window, I saved the window arrangement and have it open on program start.
• Appearance > General > Theme: Dark

Compatibility

To test if your terminal and font support it, check that all the necessary characters are supported by copying the following command to your terminal: echo "\ue0b0 \u00b1 \ue0a0 \u27a6 \u2718 \u26a1 \u2699". The result should look like this:

What do the icons mean?

• If the previous command failed (✘)
• Git status
  • Dirty working directory (±, color change)
• Elevated (root) privileges (⚡)
• Job output (⚙)

Update export path for node modules in your ~/.zshrc file:

#NODE MODULES EXPORT
export PATH="$HOME/.npm-packages/bin:$PATH"

Your npm packages directory may be different. This is a custom path I have them installing into.

Removing username@hostname from command prompt can be done by adding the following to the .zshrc file:

DEFAULT_USER=`whoami`
# Those are back ticks, not single quotes!

VS Code Integrated Terminal

If you use the integrated terminal in VS Code, you will also need to add the Powerline font you used to share the same font compatibility. You can add the font by going into VS Code settings and add the Powerline font to the font family section.

The settings can also be exported/ modified via the following ID:

terminal.integrated.fontFamily:  'Cousine for Powerline'

Before font setup:

After font setup:

Enjoy swapping themes, fonts, colors to your liking.

The more shortcut friendly you are, the more busy your macOS dock can become. Adding spacers to your dock can help organize those cluttered icons.

This isn’t a drag and drop GUI hack, but roll up your sleeves for a two line terminal process that will make your desktop look much cleaner.

Step 1: Create the spacer

defaults write com.apple.dock persistent-apps -array-add '{tile-type="spacer-tile";}'

Step 2: Reset the Dock

killall Dock

The dock service is basically restarted and a newly added spacer will be available. Drag into the location as you please. Repeat both 1 & 2 for any additional spacers.

Remove a Spacer

You can right click on the empty space and select the “Remove from Dock” option just like any other icon.