Initial commit

skills/backend-endpoint/functions/route_validator.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+Validate API route path follows REST conventions.
+
+Ensures routes are RESTful, properly formatted, and follow best practices.
+"""
+
+import sys
+import re
+import argparse
+
+# HTTP methods and their typical use cases
+HTTP_METHODS = {
+    'GET': 'Retrieve resource(s)',
+    'POST': 'Create new resource',
+    'PUT': 'Replace entire resource',
+    'PATCH': 'Update part of resource',
+    'DELETE': 'Remove resource',
+}
+
+def validate_route_path(path, method=None):
+    """
+    Validate route path against REST conventions.
+
+    Args:
+        path: API route path
+        method: HTTP method (optional)
+
+    Returns:
+        tuple: (is_valid: bool, error_message: str or None)
+    """
+    # Check path starts with /
+    if not path.startswith('/'):
+        return False, "Route path must start with '/'"
+
+    # Check no trailing slash (except for root)
+    if len(path) > 1 and path.endswith('/'):
+        return False, "Route path should not end with '/' (except root '/')"
+
+    # Check for double slashes
+    if '//' in path:
+        return False, "Route path contains double slashes '//'"
+
+    # Check path segments
+    segments = [s for s in path.split('/') if s]
+
+    # Check resource naming (should be plural for collections)
+    for i, segment in enumerate(segments):
+        # Skip API prefix and version
+        if segment in ('api', 'v1', 'v2', 'v3'):
+            continue
+
+        # Skip path parameters
+        if segment.startswith(':') or (segment.startswith('{') and segment.endswith('}')):
+            continue
+
+        # Check resource naming
+        if not segment.islower():
+            return False, f"Resource '{segment}' should be lowercase"
+
+        # Check for underscores vs hyphens (prefer hyphens)
+        if '_' in segment:
+            suggested = segment.replace('_', '-')
+            return False, f"Use hyphens instead of underscores: '{segment}' → '{suggested}'"
+
+    # Method-specific validation
+    if method:
+        method = method.upper()
+        if method not in HTTP_METHODS:
+            return False, f"Invalid HTTP method: {method}. Use: {', '.join(HTTP_METHODS.keys())}"
+
+        # Check method matches path intent
+        if method == 'POST' and segments and segments[-1].startswith(':'):
+            return False, "POST endpoints should target collections, not specific resources (remove :id)"
+
+        if method in ('PUT', 'PATCH', 'DELETE'):
+            # These methods typically need an ID parameter
+            if not any(s.startswith(':') or (s.startswith('{') and s.endswith('}')) for s in segments):
+                return False, f"{method} endpoints typically need a resource ID parameter (e.g., /:id)"
+
+    return True, None
+
+def suggest_valid_path(path):
+    """
+    Suggest a valid route path if the provided one is invalid.
+
+    Args:
+        path: Invalid route path
+
+    Returns:
+        str: Suggested valid path
+    """
+    # Remove trailing slash
+    if path.endswith('/') and len(path) > 1:
+        path = path.rstrip('/')
+
+    # Fix double slashes
+    while '//' in path:
+        path = path.replace('//', '/')
+
+    # Convert to lowercase and replace underscores
+    segments = path.split('/')
+    fixed_segments = []
+    for segment in segments:
+        if segment.startswith(':') or (segment.startswith('{') and segment.endswith('}')):
+            fixed_segments.append(segment)
+        else:
+            fixed_segments.append(segment.lower().replace('_', '-'))
+
+    suggested = '/'.join(fixed_segments)
+
+    # Ensure starts with /
+    if not suggested.startswith('/'):
+        suggested = '/' + suggested
+
+    return suggested
+
+def main():
+    parser = argparse.ArgumentParser(description='Validate REST API route path')
+    parser.add_argument('--path', required=True, help='Route path to validate')
+    parser.add_argument('--method', help='HTTP method (GET, POST, PUT, PATCH, DELETE)')
+    parser.add_argument('--suggest', action='store_true', help='Suggest a valid path if invalid')
+
+    args = parser.parse_args()
+
+    is_valid, error = validate_route_path(args.path, args.method)
+
+    if is_valid:
+        print(f"✅ '{args.path}' is a valid route path")
+        if args.method:
+            print(f"   Method: {args.method.upper()} - {HTTP_METHODS[args.method.upper()]}")
+        sys.exit(0)
+    else:
+        print(f"❌ Invalid route path: {error}", file=sys.stderr)
+
+        if args.suggest:
+            suggested = suggest_valid_path(args.path)
+            print(f"💡 Suggested path: {suggested}", file=sys.stderr)
+
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()