Building Your First API with Flask

Introduction

Today, we'll create a simple student management API using Flask. Don't worry if some terms sound complex now - I'll explain everything as we go. In this API project, I will handle 5 main operations (CRUD operations). They are,

• GET all students: View the complete student list
• GET single student: View details of one student
• POST new student: Add a new student
• PUT update student: Modify existing student
• DELETE student: Remove a student

What is Flask?

Flask is like a lightweight toolbox for building web applications in Python. It's perfect for beginners for the following reasons.

• It's simple to set up
• Requires minimal code to get started
• Gives you quick results to stay motivated

Now, open your code editor and create a new Python file.

Step 1. The Basic Setup

Create a virtual environment and install the flask module using the pip command, and once the installation is complete, we can now start writing code for our Flask API.

from flask import Flask, jsonify, request
app = Flask(__name__)

Here, in the first line, from the flask module I have imported Flask, class, jsonify method, and request. The Flask class is something we need to create our Flask application; jsonify helps us convert Python dictionaries to JSON format, and request helps us access data sent to our API. In the next line, I am creating a Flask application instance.

Step 2. Temporarily Storing Students Data

students = [
    {"id": 1, "name": "Riya", "age": 24},
    {"id": 2, "name": "Sara", "age": 22}
]

For now, I am using a simple Python list to store the student data. In real apps, you'd use a proper database.

Step 3. Getting All Students (Read)

Here, I will create an endpoint to read students' data from the students list.

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

Here, @app.route is a decorator that tells Flask what URL triggers our function. /students is the endpoint path, and methods=['GET'] specifies that this only responds to GET requests. In the next line, I created a function named get_students() in which I converted students list in json using jsonify and returned that json.

Now, we can run the app and hit the endpoint that we get for me it is http://localhost:5000/students in the postman.

This is what our output will look like in Postman.

Step 4. Getting a Single Student (Read)

Now, for getting a single student, I will create another endpoint.

@app.route('/students/<int:student_id>', methods=['GET'])
def get_student(student_id):
    student = next((s for s in students if s['id'] == student_id), None)
    if student:
        return jsonify(student)
    return jsonify({"error": "Student not found"}), 404

Here, I created a route in which <int:student_id> captures a number from the URL and passes it to our function. In the next line, I created a function to get a student with an ID. In the next line, using next(), I am trying to find the first student matching student_id, and if no student is found, None will be the default value. In the next line, if the student exists, I return that student data; else, I create a JSON that contains an error message, and I also return a 404 status code for "Not Found".

Now, let's run the project once again and hit this endpoint using Postman.

Step 5. Adding a New Student (Create)

@app.route('/students', methods=['POST'])
def add_student():
    data = request.json
    if "name" not in data or "age" not in data:
        return jsonify({"error": "Invalid data"}), 400
    
    new_student = {
        "id": len(students) + 1,
        "name": data["name"],
        "age": data["age"]
    }
    
    students.append(new_student)
    return jsonify(new_student), 201

Here, I created an endpoint for the post method, and I am specifying that using methods=['POST']; this denotes that this endpoint accepts POST requests. In the next line, I created another function to add a new student to the list. Whatever JSON data is coming in the request, I am storing it in a variable. Then, I added a line for checking whether the incoming data is proper or not. If not, I am returning an error message with a 400 status. If it was, I added that data to the existing student list and returned that student data and a 201 status, denoting successful creation of data.

Now, let's run the project once again and hit this endpoint using Postman.

Here, I added a new student by passing the json in the body and when I hit this request, 201 status is returned along with the created student.

Step 6. Updating a Student (Update)

Now, let's update an existing record using the PUT method.

@app.route('/students/<int:student_id>', methods=['PUT'])
def update_student(student_id):
    student = next((s for s in students if s["id"] == student_id), None)
    
    if not student:
        return jsonify({"error": "Student not found"})
    
    data = request.json
    student["name"] = data.get("name", student["name"]) 
    student["age"] = data.get("age", student["age"])
    
    return jsonify(student)

Here, I created a route for the PUT method and then created a function that takes student_id as a parameter. In the next line, I am checking whether this student_id exists or not in the students list. If not, I am returning an error message. If a student exists, then use the data.get() I am safely getting the values present in the request JSON with a fallback to existing values. PUT will only update provided fields, which means partial updates are allowed.

Now, let's run the project once again and hit this endpoint using Postman.

Here, I updated the data of student ID 3 and got 200 as the status code and the updated data of student ID 3.

Step 7. Deleting a Student (Delete)

Now, let's see how we can delete a record using the DELETE method.

@app.route('/students/<int:student_id>', methods=['DELETE'])
def delete_student(student_id):
    global students
    student = next((s for s in students if s["id"] == student_id), None)
    
    if not student:
        return jsonify({"error": "Student not found"})
    
    students = [s for s in students if s["id"] != student_id]
    return jsonify({"message": "Student deleted successfully"})

Here, I created a route for the DELETE method and then created a delete_student() function to delete a student from our list using their unique ID. When a DELETE request is sent to /students/<student_id>, the function first checks if a student with that ID exists. If the student is found, we remove them from the list and return a confirmation message. If not, we return an error message saying the student wasn't found. This ensures that we don't accidentally try to delete a student who isn't there.

Now, let's run the project once again and hit this endpoint using Postman.

Here, I deleted a student whose ID is 3. and got the 200 status code denoting success and also got a message in the json.

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

Here, I am ensuring that the script runs only when executed directly (not when imported as a module) and if the script is imported into another program, this block will not execute. And the next line starts the Flask web server.

Conclusion

Here, we successfully created a Flask API project and tested it using Postman.