{"id":5170,"date":"2026-11-18T21:19:27","date_gmt":"2026-11-18T21:19:27","guid":{"rendered":"https:\/\/bitflow-solutions.com\/guias-tecnicas\/build-rest-api-fastapi-windows\/"},"modified":"2026-11-18T21:19:27","modified_gmt":"2026-11-18T21:19:27","slug":"build-rest-api-fastapi-windows","status":"publish","type":"bf_guia","link":"https:\/\/bitflow-solutions.com\/en\/guias-tecnicas\/build-rest-api-fastapi-windows\/","title":{"rendered":"How to build a REST API with FastAPI on Windows: prerequisites, commands and first deployment"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">In this guide we build a REST API from scratch on <strong>Windows<\/strong> with <strong>FastAPI<\/strong>, the Python framework for APIs: a task service with endpoints to list, create and retrieve tasks, automatic documentation, tests and a container ready to deploy. Every command is typed in <strong>PowerShell<\/strong>, and you have the same steps in the <strong>README.md<\/strong> on the left.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What you\u2019ll learn<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Set up Python on Windows and a virtual environment for the project.<\/li>\n\n\n<li>Build a REST API with FastAPI and data models validated with Pydantic.<\/li>\n\n\n<li>Use the interactive documentation that FastAPI generates on its own (<code>\/docs<\/code>).<\/li>\n\n\n<li>Test the API from PowerShell and with automated tests (pytest).<\/li>\n\n\n<li>Package it in a Docker container ready to deploy.<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Prerequisites<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Windows 10 or 11<\/strong> with <strong>PowerShell<\/strong> (it comes preinstalled: search for it in the Start menu).<\/li>\n\n\n<li><strong>Python 3.10 or later<\/strong> (step 1 installs it if you don\u2019t have it).<\/li>\n\n\n<li><strong>Visual Studio Code<\/strong> with Microsoft\u2019s <em>Python<\/em> extension, or the editor of your choice.<\/li>\n\n\n<li>Basic knowledge of Python and of what a REST API is (GET, POST, JSON).<\/li>\n\n\n<li><strong>Docker Desktop<\/strong> with WSL 2, only for the last step (optional).<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Step by step<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1. Install Python and check it works<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Open PowerShell and install Python with <code>winget<\/code>, the Windows package manager:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>winget install -e --id Python.Python.3.12<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">You can also download it from python.org; in that case, tick <strong>\u201cAdd python.exe to PATH\u201d<\/strong> on the installer\u2019s first screen. <strong>Close and reopen PowerShell<\/strong> and check that it responds:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>python --version\npip --version<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">2. Create the project and its virtual environment<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The virtual environment isolates this project\u2019s dependencies from the rest of the machine. Once it is activated, the PowerShell prompt starts with <code>(.venv)<\/code>.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>mkdir C:\\projects\\tasks-api\ncd C:\\projects\\tasks-api\npython -m venv .venv\n.venv\\Scripts\\Activate.ps1<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">3. Install FastAPI<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The <code>fastapi[standard]<\/code> package includes the server (Uvicorn), the <code>fastapi<\/code> command-line tool and everything needed for testing. Save the dependencies to <code>requirements.txt<\/code>, in UTF-8 so that Docker can read it too:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>pip install \"fastapi[standard]\"\npip freeze | Out-File -Encoding utf8 requirements.txt<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">4. Write your first API<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Open the folder in Visual Studio Code and, if it asks which Python interpreter to use, choose the one in <code>.venv<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>code .<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Create the <code>main.py<\/code> file:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>from fastapi import FastAPI\n\napp = FastAPI(title=\"Tasks API\")\n\n\n@app.get(\"\/\")\ndef home():\n    return {\"message\": \"Hello from FastAPI\"}<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">5. Start the development server<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">In PowerShell, with the virtual environment activated:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>fastapi dev main.py<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Open <code>http:\/\/127.0.0.1:8000<\/code> and you will see the message in JSON. At <code>http:\/\/127.0.0.1:8000\/docs<\/code> you have the interactive documentation (Swagger UI), generated from the code, where you can try out each endpoint. The server reloads automatically when you save; to stop it, press <code>Ctrl + C<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">6. Add a model and the task endpoints<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">With <strong>Pydantic<\/strong> you define the shape of the data: FastAPI validates every request, returns a 422 error if it doesn\u2019t match and documents the contract in <code>\/docs<\/code>. Replace <code>main.py<\/code> with:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>from fastapi import FastAPI, HTTPException\nfrom pydantic import BaseModel\n\napp = FastAPI(title=\"Tasks API\")\n\n\nclass NewTask(BaseModel):\n    title: str\n    done: bool = False\n\n\nclass Task(NewTask):\n    id: int\n\n\ntasks: list[Task] = []\n\n\n@app.get(\"\/\")\ndef home():\n    return {\"message\": \"Hello from FastAPI\"}\n\n\n@app.get(\"\/tasks\")\ndef list_tasks() -&gt; list[Task]:\n    return tasks\n\n\n@app.post(\"\/tasks\", status_code=201)\ndef create_task(new: NewTask) -&gt; Task:\n    task = Task(id=len(tasks) + 1, **new.model_dump())\n    tasks.append(task)\n    return task\n\n\n@app.get(\"\/tasks\/{task_id}\")\ndef get_task(task_id: int) -&gt; Task:\n    for task in tasks:\n        if task.id == task_id:\n            return task\n    raise HTTPException(status_code=404, detail=\"Task not found\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The tasks are kept in memory to keep the example simple: they are lost when the server restarts. In a real project they would go to a database.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">7. Test the API from PowerShell<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Open a second PowerShell window (the first one is still running the server) and use <code>Invoke-RestMethod<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Invoke-RestMethod -Method Post -Uri http:\/\/127.0.0.1:8000\/tasks -ContentType \"application\/json\" -Body '{\"title\": \"First task\"}'\n\nInvoke-RestMethod http:\/\/127.0.0.1:8000\/tasks\nInvoke-RestMethod http:\/\/127.0.0.1:8000\/tasks\/1<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">8. Add automated tests<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Create <code>test_main.py<\/code> next to <code>main.py<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>from fastapi.testclient import TestClient\n\nfrom main import app\n\nclient = TestClient(app)\n\n\ndef test_create_and_get_task():\n    response = client.post(\"\/tasks\", json={\"title\": \"First task\"})\n    assert response.status_code == 201\n    task = response.json()\n\n    response = client.get(f\"\/tasks\/{task['id']}\")\n    assert response.status_code == 200\n    assert response.json()[\"title\"] == \"First task\"\n\n\ndef test_task_that_does_not_exist():\n    assert client.get(\"\/tasks\/999\").status_code == 404<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Install pytest and run the tests with the virtual environment activated:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>pip install pytest\npytest<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">9. Package it in a container (optional)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">With Docker Desktop open, create a file called <code>Dockerfile<\/code>, with no extension, in the project folder:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>FROM python:3.12-slim\n\nWORKDIR \/code\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\nCOPY main.py .\n\nCMD [\"fastapi\", \"run\", \"main.py\", \"--port\", \"80\"]<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Build the image and run it:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>docker build -t tasks-api .\ndocker run -p 8000:80 tasks-api<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The API is available at <code>http:\/\/127.0.0.1:8000<\/code>, ready to deploy on Kubernetes, Azure Container Apps or any container platform.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Common errors<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">\u201cpython\u201d opens the Microsoft Store<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Windows ships with aliases that send you to the Store. Turn them off in <em>Settings \u2192 Apps \u2192 Advanced app settings \u2192 App execution aliases<\/em> (python.exe and python3.exe) and reopen PowerShell.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\u201cRunning scripts is disabled on this system\u201d<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">This appears when you activate the virtual environment. Allow local scripts for your user only and run <code>.venv\\Scripts\\Activate.ps1<\/code> again:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">\u201cfastapi\u201d is not recognised as a command<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The virtual environment is not activated (the prompt doesn\u2019t start with <code>(.venv)<\/code>) or FastAPI was installed outside it. Activate it and repeat step 3.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Port 8000 is already in use<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Another application is using it. Start on a different port and use that address:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>fastapi dev main.py --port 8001<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">\u201ccurl\u201d doesn\u2019t work like in examples on the internet<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">In Windows PowerShell, <code>curl<\/code> is an alias for <code>Invoke-WebRequest<\/code> and doesn\u2019t understand curl\u2019s options. Use <code>Invoke-RestMethod<\/code> as in step 7, or <code>curl.exe<\/code> if you want the real curl.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The API responds 422 Unprocessable Entity<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The request body doesn\u2019t match the model: <code>title<\/code> is missing, has a different type or the JSON is not valid. The response tells you which field fails; check it in <code>\/docs<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Docker can\u2019t read requirements.txt<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">If you created it with <code>&gt;<\/code> in Windows PowerShell, the file ends up in UTF-16. Generate it again with <code>Out-File -Encoding utf8<\/code> as in step 3.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Next steps<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Store the tasks in a database, for example PostgreSQL with SQLModel.<\/li>\n\n\n<li>Protect the endpoints with OAuth 2.0 and JWT tokens (see the OpenAPI 3 contract with OAuth and API Key guide).<\/li>\n\n\n<li>Publish it behind an API Gateway with quotas and versioned contracts.<\/li>\n\n\n<li>Automate testing and deployment with a CI\/CD pipeline.<\/li>\n\n<\/ul>\n\n\n","protected":false},"excerpt":{"rendered":"<p>From zero to a tasks API with FastAPI on Windows and PowerShell: Python with winget, a virtual environment, endpoints with Pydantic, automatic documentation, tests and a Docker container.<\/p>\n","protected":false},"featured_media":0,"template":"","bf_tecnologia":[101],"bf_nivel":[108],"class_list":["post-5170","bf_guia","type-bf_guia","status-publish","hentry","bf_tecnologia-apis-en","bf_nivel-basic"],"acf":[],"_links":{"self":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5170","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia"}],"about":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/types\/bf_guia"}],"version-history":[{"count":0,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5170\/revisions"}],"wp:attachment":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/media?parent=5170"}],"wp:term":[{"taxonomy":"bf_tecnologia","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_tecnologia?post=5170"},{"taxonomy":"bf_nivel","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_nivel?post=5170"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}