First REST API with Flask

You've mastered Python syntax, data structures, and even some command-line tools. But when you need to share data between a frontend, a mobile app, or another server, you need an API — and building your first REST API with Flask is the fastest way to get there. Without an API, your Python skills stay locked inside a single script, invisible to the world. In this lesson, you'll create a working REST API from scratch, understand the core concepts behind HTTP methods and endpoints, and learn to debug the most common pitfalls — so you can ship your first backend service with confidence.

The Problem This Lesson Solves

Imagine you've built a brilliant Python script that analyzes text, tracks expenses, or manages a to-do list. It works perfectly when you run it on your machine. But how does your React frontend call it? How does your mobile app fetch that data? The answer is an API — a set of rules that let different software systems talk to each other.

REST (Representational State Transfer) is the most common architectural style for web APIs. It uses standard HTTP methods like GET, POST, PUT, and DELETE to interact with resources. If you don't understand REST, you risk building an endpoint that works on your machine but breaks in production, or worse, an API that's insecure and slow. This lesson strips away the confusion and shows you exactly how to build a simple, robust REST API with Flask.

Core Concept / Mental Model

Think of a REST API as a waiter in a restaurant. Your client (the diner) makes a request: "I'd like the menu of the day" (GET), "Please add a new dish to the menu" (POST), "Update this dish's price" (PUT), or "Remove this dish" (DELETE). The waiter (your API) takes that request, talks to the kitchen (your database or data structure), and brings back a response — usually in JSON format.

Here are the key terms you'll need:

• Resource: A thing your API manages, like users, posts, or tasks.
• Endpoint: A URL path that maps to a resource, e.g., /api/tasks.
• HTTP Method: The action you want to perform — GET (read), POST (create), PUT (update), DELETE (delete).
• Status Code: The result of the request — 200 for success, 404 for not found, 201 for created, 400 for a bad request.
• JSON: The data format used for input and output — human-readable and language-agnostic.

Pro tip: You don't need a database to start. You can use a simple Python list or dictionary as your "database" to learn the mechanics. Swap it later for SQLite or PostgreSQL when you're ready.

How It Works Step by Step

Building a REST API with Flask follows a predictable pattern. Here's the logical flow:

1. Set up the environment: Create a virtual environment and install Flask.
2. Initialize the app: Create a Flask application instance.
3. Define routes and methods: Use decorators like @app.route('/api/tasks', methods=['GET']) to expose endpoints.
4. Process requests: Read data from request.json or URL parameters.
5. Return JSON responses: Use jsonify() to convert Python data to JSON with proper status codes.
6. Test and debug: Use a browser, curl, or Postman to verify each endpoint.

Let's apply this in a concrete walkthrough.

Hands-On Walkthrough

Step 1: Set Up Your Project

Create a new directory and a virtual environment:

mkdir flask-api-tutorial
cd flask-api-tutorial
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install flask

Step 2: Write a Minimal Flask App

Create a file named app.py with the following code:

from flask import Flask, jsonify, request

app = Flask(__name__)

# In-memory "database"
tasks = []
next_id = 1

@app.route('/')
def home():
    return "Welcome to the Task API!"

@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    """Return all tasks as JSON."""
    return jsonify(tasks)

@app.route('/api/tasks', methods=['POST'])
def create_task():
    """Create a new task from JSON body."""
    global next_id
    data = request.get_json()
    if not data or not data.get('title'):
        return jsonify({'error': 'Title is required'}), 400
    task = {
        'id': next_id,
        'title': data['title'],
        'done': data.get('done', False)
    }
    tasks.append(task)
    next_id += 1
    return jsonify(task), 201

if __name__ == '__main__':
    app.run(debug=True)

Run the app:

python app.py

You'll see output like Running on http://127.0.0.1:5000. Open that URL in a browser — you'll see the welcome message.

Step 3: Test Your API with curl

In a second terminal, test the endpoints:

# GET all tasks (should be empty array)
curl http://127.0.0.1:5000/api/tasks

# Add a task
curl -X POST http://127.0.0.1:5000/api/tasks -H "Content-Type: application/json" -d '{"title": "Learn Flask"}'

# GET again
curl http://127.0.0.1:5000/api/tasks

Expected output: The first GET returns []. The POST returns the created task with status 201. The second GET shows:

[{"done": false, "id": 1, "title": "Learn Flask"}]

Step 4: Add GET for a Single Task and DELETE

Extend app.py with these routes:

@app.route('/api/tasks/<int:task_id>', methods=['GET'])
def get_task(task_id):
    """Return a specific task by ID."""
    task = next((t for t in tasks if t['id'] == task_id), None)
    if task is None:
        return jsonify({'error': 'Task not found'}), 404
    return jsonify(task)

@app.route('/api/tasks/<int:task_id>', methods=['DELETE'])
def delete_task(task_id):
    """Delete a task by ID."""
    global tasks
    task = next((t for t in tasks if t['id'] == task_id), None)
    if task is None:
        return jsonify({'error': 'Task not found'}), 404
    tasks = [t for t in tasks if t['id'] != task_id]
    return jsonify({'message': 'Task deleted'})

Restart the server and test:

curl http://127.0.0.1:5000/api/tasks/1
curl -X DELETE http://127.0.0.1:5000/api/tasks/1

Pro tip: Use debug=True during development so the server auto-reloads after code changes. Never enable debug mode in production — it can expose sensitive data and execute arbitrary code.

Compare Options / When to Choose What

Flask is lightweight and flexible, but it's not the only web framework. How does it compare to others?

When to use Flask: - You want total control over each part of your API. - You're building a microservice or a small to medium project. - You're learning web development and want to understand HTTP fundamentals.

When to avoid Flask: - You need a full framework with built-in admin panel and ORM from day one (choose Django). - You're building a highly concurrent API with heavy I/O and want async without extra dependencies (choose FastAPI).

As an alternative, you can add the Flask-RESTful extension for more structured API building, or use Flask-Smorest for OpenAPI documentation — but plain Flask is perfectly fine to start.

Troubleshooting & Edge Cases

Common Mistakes and Fixes

1. Forgot to call jsonify() — Returning a Python dict directly from a route works, but in older Flask versions it's not automatic. Always use jsonify() for consistency.

2. Using debug=True in production — This can lead to a security vulnerability. Set debug=False or use environment variables for configuration.

3. Not validating input — A POST request might have missing fields or wrong types. Always check for required fields and use try/except to handle malformed JSON.

4. Mutable global state — Using a global list for tasks works, but it resets on restart and isn't thread-safe. For production, use a database.

Edge Cases

• Invalid JSON body: request.get_json() returns None if the content-type isn't JSON. Handle it: python data = request.get_json(silent=True) if data is None: return jsonify({'error': 'Invalid JSON'}), 400
• ID not found: Always return a proper 404 status code, not an empty result.
• Type coercion: data.get('done', False) might receive a non-boolean value. Consider validating types.

What You Learned & What's Next

You've built your first REST API with Flask. You can now:

• Explain the core concept of REST and why APIs matter.
• Set up a Flask app and define routes for GET and POST.
• Return JSON responses with jsonify() and appropriate status codes.
• Test your endpoints with curl and troubleshoot common errors.

Your next step in the Python web development track is to connect this API to a real database (likely PostgreSQL via SQLAlchemy). That will let you persist data across server restarts and add authentication and more robust error handling. You're on track to building production-ready backends!