docs/adding_routes.md

Adding New Routes

This document explains how to add new routes to the application using the dynamic route registration system.

Overview

The application now uses a dynamic route registration system that automatically discovers and registers all Flask blueprints in the routes directory. This means you no longer need to manually import and register blueprints in app.py.

How to Add a New Route

1. Create a new route file

   Create a new Python file in the appropriate location in the routes directory. For a v1 API endpoint, you would typically place it in a subdirectory under routes/v1/ based on the functionality.

   For example:

   routes/v1/email/send_email.py
   

2. Define your Blueprint

   In your route file, define a Flask Blueprint with a unique name. Make sure to follow the naming convention:

   # routes/v1/email/send_email.py
   from flask import Blueprint, request
   from services.authentication import authenticate
   from app_utils import queue_task_wrapper
   
   v1_email_send_bp = Blueprint('v1_email_send', __name__)
   
   @v1_email_send_bp.route('/v1/email/send', methods=['POST'])
   @authenticate
   @queue_task_wrapper(bypass_queue=False)
   def send_email(job_id, data):
       """
       Send an email
       
       Args:
           job_id (str): Job ID assigned by queue_task_wrapper
           data (dict): Request data containing email details
       
       Returns:
           Tuple of (response_data, endpoint_string, status_code)
       """
       # Your implementation here
       endpoint = "/v1/email/send"
       
       # Return response
       return {"message": "Email sent"}, endpoint, 200
   

3. That's it!

   No need to modify app.py. The blueprint will be automatically discovered and registered when the application starts.

Naming Conventions

When creating new routes, please follow these naming conventions:

1. Blueprint names: Use the format {version}_{category}_{action}_bp

   • Example: v1_email_send_bp for sending emails

2. Route paths: Use the format /{version}/{category}/{action}

   • Example: /v1/email/send

3. File structure: Place files in directories that match the route structure

   • Example: routes/v1/email/send_email.py

Testing Your Route

After adding your route, restart the application and your new endpoint should be available immediately.

Troubleshooting

If your route isn't being registered:

1. Check logs for any import errors
2. Ensure your blueprint variable is defined at the module level
3. Verify the blueprint name follows the naming convention
4. Make sure your Python file is in the correct directory under routes/