Building REST APIs with Flask

# CHAPTER 13

Building REST APIs with Flask #

1. Introduction #

2. Learning Objectives #

• Understand the difference between rendering templates and returning JSON.

• Use Flask's jsonify function to serialize Python dictionaries.

• Extract incoming JSON payloads using request.getjson().

from flask import Flask, jsonify

app = Flask(__name__)

# A simple API endpoint
@app.route('/api/status', methods=['GET'])
def get_status():
    # 1. Create a standard Python dictionary
    data = {
        "status": "online",
        "version": "1.0.4",
        "active_users": 42
    }
    
    # 2. Convert the dictionary to JSON and return it!
    return jsonify(data)

*If you visit /api/status in your browser, you won't see a webpage. You will see raw text data perfectly formatted in JSON.*

5. Step 2: Extracting Database Data (Serialization) #

@app.route('/api/users', methods=['GET'])
def get_users():
    users = User.query.all()
    
    # Create an empty list
    user_list = []
    
    # Loop through the database objects and convert them to dictionaries
    for user in users:
        user_data = {
            "id": user.id,
            "username": user.username,
            "email": user.email
        }
        user_list.append(user_data)
        
    return jsonify({"users": user_list})

6. Step 3: Accepting JSON Payloads (POST) #

from flask import request

@app.route('/api/users/create', methods=['POST'])
def create_api_user():
    # Extract the raw JSON from the incoming request
    data = request.get_json()
    
    # Access the data exactly like a Python dictionary
    uname = data.get('username')
    uemail = data.get('email')
    
    # Save to database...
    new_user = User(username=uname, email=uemail)
    db.session.add(new_user)
    db.session.commit()
    
    # Return a success message and an HTTP 201 Created status code
    return jsonify({"message": "User successfully created!", "id": new_user.id}), 201

7. Backend Workflow: REST Principles #

For example, manipulating "Posts":

• GET /api/posts (Fetch all posts)

• POST /api/posts (Create a new post)

• GET /api/posts/5 (Fetch post #5)

• PUT /api/posts/5 (Completely overwrite post #5)

• DELETE /api/posts/5 (Delete post #5)

Notice we did not use URLs like /api/posts/create or /api/posts/delete/5. The URL represents the *resource* (/api/posts), and the HTTP Method (GET, POST, DELETE) dictates the *action*.

8. Best Practices #

• Marshmallow: Manually looping through database objects to convert them into dictionaries (as seen in Step 2) is incredibly tedious. In production, Flask developers use an extension called Flask-Marshmallow. It acts as an automated translator, turning complex database models into JSON schemas in just two lines of code.

9. Common Mistakes #

• TypeErrors with JSON: Beginners often try to return jsonify(User.query.all()). This will immediately crash the server. jsonify only understands basic Python datatypes (strings, integers, lists, dictionaries). It has absolutely no idea how to convert a complex SQLAlchemy User object into text. You must serialize (translate) the object into a dictionary first.

10. Exercises #

1. 1. Explain the fundamental difference between building an application using Server-Side Rendering (using rendertemplate) versus building an API (using jsonify). Who handles the HTML generation in each scenario?

16. Next Chapter Recommendation #