Aug 175 min read

Building a REST API with Python and Flask: A Beginner's Guide

Introduction

In today’s digital world, APIs (Application Programming Interfaces) are the backbone of modern applications. They allow different software systems to communicate with each other, enabling a seamless exchange of data and services. Among the various types of APIs, REST (Representational State Transfer) is one of the most popular due to its simplicity and scalability.

In this guide, we’ll dive deep into building a REST API using Python and Flask. Flask is a micro web framework that is simple yet powerful, making it an excellent choice for both beginners and experienced developers. By the end of this guide, you’ll have a solid understanding of how to create, manage, and extend a REST API with Flask.

First learn python beginners guide for better understanding.

Why Choose Flask for Building REST APIs?

Flask is a micro-framework for Python based on Werkzeug and Jinja2. Here’s why it’s a great choice for building REST APIs:

Lightweight and Flexible: Flask doesn’t force you to use particular tools or libraries. This flexibility allows you to build a REST API that suits your needs.
Easy to Learn: Flask’s simplicity makes it an excellent framework for beginners who want to understand the basics of web development.
Extensible: Flask provides extensions for database integration, form handling, authentication, and more, allowing you to scale your application as needed.
Active Community: With a large community of developers, Flask has plenty of resources, tutorials, and third-party extensions available.

Getting Started

Prerequisites

Before we start, ensure you have the following installed on your machine:

Python 3.x: Python is the primary programming language we’ll use. You can download it from the official Python website.
pip: Python’s package installer, which is usually bundled with Python. You’ll use pip to install Flask and other dependencies.
A text editor or IDE: Choose one you’re comfortable with, such as VSCode, PyCharm, or Sublime Text.

Setting Up Your Environment

Create a Virtual Environment (Optional but Recommended)

A virtual environment helps isolate your project’s dependencies from your global Python installation. Here’s how to create and activate a virtual environment:

# Install virtualenv if you don't have it already
pip install virtualenv

# Create a new virtual environment
virtualenv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

Install Flask

With your virtual environment activated (if you created one), install Flask:

pip install Flask

Step 1: Creating a Basic Flask Application

Start by creating a new directory for your project and navigating into it:

mkdir flask_rest_api 
cd flask_rest_api

Inside this directory, create a file named app.py. This will be the main file for your Flask application.

Writing Your First Flask Route

Let’s create a basic Flask application with a single route that returns a welcome message:

from flask import Flask

app = Flask(__name__)

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

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

This simple script does the following:

Imports Flask: We import the Flask class from the flask module.
Creates a Flask Application Instance: app = Flask(__name__) creates an instance of the Flask class.
Defines a Route: The @app.route('/') decorator maps the root URL ("/") to the home function.
Starts the Development Server: app.run(debug=True) runs the application in debug mode, allowing you to see errors and changes in real-time.

Running Your Flask Application

To run your application, use the following command:

python app.py

Visit http://127.0.0.1:5000/ in your browser, and you should see the message "Welcome to the Flask REST API!".

Step 2: Designing the REST API

Before diving into coding, let’s outline what our REST API will look like. We’ll create an API for managing a collection of books. Each book will have an id, title, and author.

Here’s a summary of the endpoints we’ll create:

GET /books: Retrieve a list of all books.
GET /books/<id>: Retrieve details of a single book by its ID.
POST /books: Add a new book to the collection.
PUT /books/<id>: Update the details of an existing book.
DELETE /books/<id>: Remove a book from the collection.

Step 3: Implementing the REST API Endpoints

Now that we have our API design, let’s start implementing it in app.py.

1. Setting Up the Data Structure

We’ll use a list of dictionaries to represent our book collection. Add the following to app.py:

books = [
    {'id': 1, 'title': '1984', 'author': 'George Orwell'},
    {'id': 2, 'title': 'To Kill a Mockingbird', 'author': 'Harper Lee'},
]

This list will serve as our in-memory database for this example.

2. Implementing the GET /books Endpoint

The first endpoint retrieves the list of all books:

from flask import Flask, jsonify

app = Flask(__name__)

books = [
    {'id': 1, 'title': '1984', 'author': 'George Orwell'},
    {'id': 2, 'title': 'To Kill a Mockingbird', 'author': 'Harper Lee'},
]

@app.route('/books', methods=['GET'])
def get_books():
    return jsonify(books)

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

jsonify(): Converts the list of books into a JSON response, which is the standard format for REST APIs.

3. Implementing the GET /books/<id> Endpoint

Next, let’s create an endpoint that retrieves a single book by its ID:

@app.route('/books/<int:id>', methods=['GET'])
def get_book(id):
    book = next((book for book in books if book['id'] == id), None)
    return jsonify(book) if book else ('', 404)

Path Parameter: <int:id> captures the book ID from the URL.
next() Function: Finds the first book with the matching ID, or returns None if not found.
404 Error: If the book is not found, the server returns a 404 (Not Found) status code.

4. Implementing the POST /books Endpoint

This endpoint allows you to add a new book to the collection:


from flask import request

@app.route('/books', methods=['POST'])
def add_book():
    new_book = request.get_json()
    books.append(new_book)
    return jsonify(new_book), 201

request.get_json(): Parses the incoming JSON request data.
Appending the New Book: The new book is added to the books list.
201 Created: Returns the new book along with a 201 status code, indicating that the resource was created successfully.

5. Implementing the PUT /books/<id> Endpoint

To update an existing book, we’ll use the PUT method:

@app.route('/books/<int:id>', methods=['PUT'])
def update_book(id):
    book = next((book for book in books if book['id'] == id), None)
    if book:
        data = request.get_json()
        book.update(data)
        return jsonify(book)
    return ('', 404)

update() Method: Updates the book’s details with the new data provided in the request.

6. Implementing the DELETE /books/<id> Endpoint

Finally, let’s create an endpoint to delete a book:

@app.route('/books/<int:id>', methods=['DELETE'])
def delete_book(id):
    global books
    books = [book for book in books if book['id'] != id]
    return ('', 204)

204 No Content: This status code indicates that the request was successful but there is no content to return.

Step 4: Testing Your API

Now that your API is complete, it’s time to test it. You can use tools like Postman or cURL to send HTTP requests to your API endpoints.

Example Test Cases

Retrieve All Books: Send a GET request to http://127.0.0.1:5000/books to get a list of all books.
Retrieve a Single Book: Send a GET request to http://127.0.0.1:5000/books/1 to retrieve the book with ID 1.
Add a New Book: Send a POST request to http://127.0.0.1:5000/books with a JSON body like {"id": 3, "title": "Brave New World", "author": "Aldous Huxley"} to add a new

TECH IDEAS

From Techies