Building a JSON API Endpoint

What is an API Endpoint and What is JSON?

An API (Application Programming Interface) is like a contract or a menu that allows two different pieces of software to talk to each other. In our case, it's how we'll define the "menu" of functions our Flask backend offers to the web browser. An API endpoint is a specific URL on our server that, when accessed, performs a task and returns data.

But in what format should that data be? The most popular format for web APIs is JSON (JavaScript Object Notation).

To get a clear understanding of what JSON is and why it's so important, please read the first part of the following article.

As you read, you'll see that a JSON object looks incredibly similar to a Python dictionary.

• Python Dictionary: {"name": "John", "age": 30}
• JSON: {"name": "John", "age": 30}

This similarity makes it very easy to work with JSON in Python.

Creating Your First JSON Endpoint

Flask makes returning JSON incredibly simple. In modern versions of Flask, if you return a Python dictionary from a route function, Flask will automatically convert it into a proper JSON response.

Let's see this in action. Take a look at this short video.

Let's write the code for our own simple API endpoint.

app.py

from flask import Flask

app = Flask(__name__)

# This is our API endpoint
@app.route('/api/status')
def api_status():
    # Create a Python dictionary
    status_data = {
        'appName': 'AI Writing Assistant',
        'version': '0.1',
        'status': 'online'
    }
    # Return the dictionary. Flask will convert it to JSON.
    return status_data

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

Run this app.py file and navigate your browser to http://127.0.0.1:5000/api/status. Instead of an HTML page, you'll see the raw JSON text. Your browser might even have a built-in viewer to format it nicely.

Using jsonify for Clearer Code

While returning a dictionary directly works, Flask provides a function called jsonify that makes your intention more explicit and gives you a bit more control. It's considered good practice to use it.

The jsonify function does two things:

1. It converts your Python dictionary into a JSON formatted string.
2. It creates a proper HTTP Response object with the Content-Type header set to application/json. This header is a signal to browsers and other clients that they are receiving JSON data.

The video below gives a great overview of building a simple API with Flask and demonstrates how to use jsonify.

Let's update our previous example to use jsonify.

app.py (updated)

from flask import Flask, jsonify  # Import jsonify

app = Flask(__name__)

@app.route('/api/status')
def api_status():
    status_data = {
        'appName': 'AI Writing Assistant',
        'version': '0.1',
        'status': 'online'
    }
    # Use jsonify to create the response
    return jsonify(status_data)

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

If you run this and visit the URL again, the result will look identical. Under the hood, however, we are being more explicit about our goal.

Testing Your API Endpoints

While you can test simple GET endpoints in your browser, it's not practical for more complex requests (like the POST requests we'll need later). Professional developers use API testing tools. One of the most popular is Postman.

These tools let you craft any kind of HTTP request (GET, POST, etc.), add headers, send JSON data, and inspect the server's response in detail.

This image shows exactly what this looks like. A request with JSON data is sent to a Flask server, which then processes it and sends a JSON response back.

The final part of the Tech With Tim video you were watching introduces Postman and shows you how to use it to test a POST request. Getting familiar with this tool now will be very helpful.

{
  "character_count": 25,
  "original_text": "Hello world this is fun",
  "word_count": 5
}

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/api/analyze/<text_to_analyze>')
def analyze_text(text_to_analyze):
    # Calculate the word and character counts
    char_count = len(text_to_analyze)
    word_count = len(text_to_analyze.split())

    # Create the dictionary for the JSON response
    analysis_result = {
        'original_text': text_to_analyze,
        'character_count': char_count,
        'word_count': word_count
    }

    # Return the result as a JSON response
    return jsonify(analysis_result)

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

Conclusion

Fantastic work! You have now learned how to create a backend API endpoint that provides raw data to any client that asks for it. This is a fundamental building block of modern web development and is the exact mechanism we will use to connect your web page's interactive elements to the powerful AI models on the backend.

Key Takeaways:

• APIs allow your frontend (browser) and backend (Flask server) to communicate using data.
• JSON is the standard data format for web APIs, using a key-value structure that looks just like a Python dictionary.
• In Flask, you can simply return a dictionary from a route, or more explicitly use the jsonify() function to create a JSON response.
• API endpoints are often tested with dedicated tools like Postman.

In our next lesson, we'll take a step back and look at organization. As our application grows with HTML files, Python code, and soon CSS and JavaScript files, we need a clean folder structure to manage everything. We'll learn the standard way to structure a Flask project to keep it tidy and maintainable.