An API (Application Programming Interface) describes a way for two computers to interact.An HTTP API allows an Internet-connected computer to send an HTTP request to another Internet-connected computerand receive a response. For example, my computer could send a request tohttp://a-weather-website-api.com/api/city=Los+Angeles and receive back data like{"high": 72, "low": 66}.

HTTP APIs often provide either data or functionality that's unique to a service, like the example API for the weather website. A weather website could provide additional API endpoints for other weather-related functionality, like upcoming forecasts or historical data. Any website can decide to offer an API if it thinks it has helpful functionality to sharewith other computers. In this project, you'll run an HTTP API that generates a random token.

The API included in this template repository has a single endpoint that generates a token. Get it up and running using the following steps:

1. Open up a terminal window by opening up the command palette (Ctrl-Shift-P or Cmd-Shift-P) and then select "Open new Terminal" command.

2. Runuvicorn in the console to start up your API application:

   uvicorn --host 0.0.0.0 webapp.main:app --reload

   You should see output similar to:

   INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)INFO:     Started reloader process [28720]INFO:     Started server process [28722]INFO:     Waiting for application startup.INFO:     Application startup complete.

   You'll get a pop-up that says your application is available at port 8000. Click the button to open it in the browser.

3. Once the site loads, click on theTry it Out button or append/docs to the URL in the address bar. The automatically generated API documentation should load and look like this:

   

4. Finally, try to interact with the API by sending a request using the self-documented page. Click on thePOST button and then on theTry it Out button:

   

🔒 Do you see the lock next to the URL of the website in the browser? That indicates the website is being served over a secure HTTPS connection which encrypts the HTTP responses. That's very important whenever an API can receive sensitive data or respond with sensitive data (like a password).

Let's say you want to change which version of Python is installed. This is something you can control.

Open.devcontainer/devcontainer.json and replace the following section:

"VARIANT":"3.8-bullseye"

with the following instruction:

"VARIANT":"3.9-bullseye"

This change instructs Codespaces to use Python 3.9 instead of 3.8.

If you make any configuration change indevcontainer.json, a box will appear after saving.

Click on rebuild. Wait for your Codespace to rebuild the VS Code environment.

Your environment comes with pre-installed extensions. You can change which extensions your Codespaces environment starts with. Here's how:

1. Open file.devcontainer/devcontainer.json and locate the following JSON elementextensions:

   "extensions": ["ms-python.python","ms-python.vscode-pylance"]

2. Add"ms-python.black-formatter" to the list of extensions. It should end up looking like the following:

   "extensions": ["ms-python.python","ms-python.vscode-pylance","ms-python.black-formatter"]

   That string is the unique identifier ofBlack Formatter, a popular extension for formatting Python code according to best practices. Adding the"ms-python.black-formatter" identifier to the list lets Codespaces know that this extension should be pre-installed upon startup.

   Reminder: When you change any configuration in the JSON file, a box will appear after saving.

   

   Click on rebuild. Wait for your Codespace to rebuild the VS Code environment.

To find the unique identifier of an extension:

• Navigate to the extension's web page, for examplehttps://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
• Locate theUnique Identifier field underMore info section on your right side.

Now, you are going to set up automatic deployment of the application using Azure plus GitHub actions! However, you first need to configure some Azure services.

1. Open theAzure Cloud Shell.
2. Use the Bash shell (not PowerShell!) for these steps.
3. If it says "You have no storage mounted", select a subscription in your account and click "Create storage". The Cloud Shell uses that storage resource to store data generated during your shell sessions.
4. Create aResource Group which will group together the different Azure resources used for the app:

az group create --name demo-fastapi --location "East US"

1. You'll see a JSON response with details about the newly created resource, for this command and all the commands that follow.
2. Create theFREEApp Service Plan:

az appservice plan create --name "demo-fastapi" --resource-group demo-fastapi --is-linux --sku FREE

1. Create a random identifier for a unique webapp name:

let "randomIdentifier=$RANDOM*$RANDOM"

1. Create theWeb App Service with a placeholder container using therandomIdentifier variable from before:

az webapp create --name "demo-fastapi-$randomIdentifier" --resource-group demo-fastapi --plan demo-fastapi --runtime "PYTHON:3.9"

1. Head to the Azure portalApp Services list and confirm that your newly created service is listed.

Next, create an Azure Service Principal, which is a special type of account that has permissions necessary to authenticate from GitHub to Azure:

1. Find the ID of your Azure Subscriptionin the Azure portal orby following this guide.
2. Create a Service Principal with a "contributor" role that is allowed to make changes to any resources in that subscription. Replace $AZURE_SUBSCRIPTION_ID with the ID you found in step 1 and run this command:

az ad sp create-for-rbac  --sdk-auth --name "github-deployer" --role contributor --scopes /subscriptions/$AZURE_SUBSCRIPTION_ID

1. Capture the output and add it as aGithub repository secret with the nameAZURE_CREDENTIALS. (If that link doesn't work, make sure you're reading this on your own copy of the repo, not the original template.)

Now that you have all the Azure resources created, you need to update the GitHub Action workflow file with the name of your webapp.

1. Find your app name. It should look something likedemo-fastapi-97709018 but with a different random number at the end,and you can find it in the Azure portal or the Cloud Shell commands.
2. Open the.github/workflows/web_app.yml file and update the value ofAZURE_WEBAPP_NAME to your app name.
3. Commit and push the changes to the Github repository:

git add .github/workflows/web_app.ymlgit commit -m "Updating workflow file"git push

Before continuing, check the following:

1. You've created an Azure Service Principal and saved it as arepository secret asAZURE_CREDENTIALS.
2. You've created anApp Service with a valid name and the site is already available with the default static content.

To deploy:

1. Navigate torepository actions. (If that link doesn't open the "Build and deploy Python app" workflow, make sure you're reading this on your own copy of the repo.)
2. SelectRun workflow and select the green button inside the pop-up to run the workflow.

Deploying can take a couple of minutes. Make sure you stream the logs in the Azure Cloud Shell to check the progress:

az webapp log tail --name $AZURE_WEBAPP_NAME --resource-group $AZURE_RESOURCE_GROUP

4. Once deployment is complete, visit your website at a URL likehttp://demo-fastapi-97709018.azurewebsites.net/,where the random number is your unique random number. You can find the website URL in the Azure portal or in the deployment logs if you forgot the number.
5. 🎉 Celebrate a successful deployment! You now have a URL that you can share with classmates, friends, and family.

You likely don't want to keep this particular website running forever in the cloud, so you should cleanup your Azure resources by destroying the resource group. You can do it in the Azure Cloud Shell by referencing the group name you created initially (demo-fastapi in the examples):

az group delete --name demo-fastapi

When deploying, you might encounter errors or problems, either on the automation part of it (GitHub Actions) or on the deployment destination (Azure Web Apps).

You can check the logs of the Github Actions workflow by selecting the latest workflow from theActions tab. Find the first step that has a broken icon next to it, and expand that step to see what went wrong in it.

If running into trouble with the Azure deployment, check logs in the portal or use the following with the Azure CLI:

az webapp log tail --name $AZURE_WEBAPP_NAME --resource-group $AZURE_RESOURCE_GROUP

Update both variables to match your environment.