api-dock 0.2.2__tar.gz → 0.3.0__tar.gz

{api_dock-0.2.2 → api_dock-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.2.2
+Version: 0.3.0
 Summary: A flexible API gateway that allows you to proxy requests to multiple remote APIs and Databases
 Author-email: Brookie Guzder-Williams <bguzder-williams@berkeley.edu>
 License: BSd 3-clause
@@ -44,6 +44,7 @@ API Dock (API(s) + (data)Base(s)/base-(for)-API(s)) a flexible API gateway that
   - [Main Configuration](#main-configuration-api_dock_configconfigyaml)
   - [Remote Configurations](#remote-configurations)
   - [SQL Database Support](#sql-database-support)
+  - [URL Query Parameters](#url-query-parameters)
 - [Using RouteMapper in Your Own Projects](#using-routemapper-in-your-own-projects)
   - [Basic Integration](#basic-integration)
   - [Framework Examples](#framework-examples)
@@ -59,6 +60,7 @@ API Dock (API(s) + (data)Base(s)/base-(for)-API(s)) a flexible API gateway that
 - **YAML Configuration**: Simple, human-readable configuration files
 - **Access Control**: Define allowed/restricted routes per remote API
 - **Version Support**: Handle API versioning in URL paths
+- **URL Query Parameters**: Declarative query parameter support for database routes with filtering, sorting, pagination, conditional logic, and direct responses
 - **Flexibility**: Quickly launch FastAPI or Flask apps, or easily integrate into any existing framework
 
 ## Install
@@ -477,6 +479,216 @@ routes:
 
 ---
 
+## URL Query Parameters
+
+Database routes support declarative URL query parameters via the `query_params` section. This lets you add filtering, sorting, pagination, conditional logic, and direct responses — all driven by the URL query string.
+
+Routes without a `query_params` section work exactly as before (full backward compatibility).
+
+### Basic Filtering with `sql`
+
+Use `sql` to add WHERE clause fragments. Each fragment is joined with `AND`. Optional by default — only included if the parameter is in the URL.
+
+```yaml
+routes:
+  - route: users
+    sql: SELECT * FROM [[users]]
+    query_params:
+      - age:
+          sql: age = {{age}}            # optional — only if ?age= provided
+      - department:
+          sql: department = '{{department}}'
+      - height:
+          sql: height < {{height}}
+          default: 200                  # always included (uses 200 if not in URL)
+```
+
+```bash
+GET /db/users?age=25&department=engineering
+# SQL: SELECT * FROM users WHERE age = 25 AND height < 200 AND department = 'engineering'
+
+GET /db/users
+# SQL: SELECT * FROM users WHERE height < 200
+```
+
+### Sorting and Pagination with `sql_append`
+
+Use `sql_append` to append clauses *after* the WHERE clause — for `ORDER BY`, `LIMIT`, `OFFSET`, etc. Fragments are appended in the order they appear in the YAML config, so **the YAML order must match valid SQL order** (ORDER BY before LIMIT before OFFSET).
+
+`sql_append` templates can reference `{{variables}}` from other parameters, including **value-only parameters** — params that only have a `default` and exist solely to provide a variable for other templates.
+
+```yaml
+routes:
+  - route: users
+    sql: SELECT * FROM [[users]]
+    query_params:
+      # WHERE clause params
+      - department:
+          sql: department = '{{department}}'
+      # Post-WHERE params
+      - sort:
+          sql_append: ORDER BY {{sort}} {{sort_direction}}
+          default: created_date
+      - sort_direction:
+          default: DESC               # value-only param — feeds into sort's template
+      - limit:
+          sql_append: LIMIT {{limit}}
+          default: 50
+      - offset:
+          sql_append: OFFSET {{offset}}  # optional — only if ?offset= provided
+```
+
+```bash
+GET /db/users?department=engineering&sort=name&sort_direction=ASC&limit=10
+# SQL: SELECT * FROM users WHERE department = 'engineering' ORDER BY name ASC LIMIT 10
+
+GET /db/users
+# SQL: SELECT * FROM users ORDER BY created_date DESC LIMIT 50
+
+GET /db/users?limit=20&offset=40
+# SQL: SELECT * FROM users ORDER BY created_date DESC LIMIT 20 OFFSET 40
+```
+
+### Required Parameters
+
+Use `required: true` to return a `400` error if the parameter is missing. Optionally provide a custom error response with `missing_response`.
+
+```yaml
+query_params:
+  - report_type:
+      sql: report_type = {{report_type}}
+      required: true
+      missing_response:
+          error: "report_type is required"
+          valid_types: ["summary", "detailed"]
+          http_status: 400
+```
+
+```bash
+GET /db/reports
+# Response (400): {"error": "report_type is required", "valid_types": [...], "http_status": 400}
+```
+
+### Direct Responses with `response`
+
+Use `response` to return a fixed JSON or string response immediately when the parameter is present (no SQL is executed).
+
+```yaml
+query_params:
+  - debug:
+      response:
+          message: Debug mode enabled
+          info: "This endpoint queries the users table"
+  - sleeping:
+      response: "Wake up! This endpoint is disabled during sleep mode."
+```
+
+```bash
+GET /db/users?debug=anything
+# Response (200): {"message": "Debug mode enabled", "info": "This endpoint queries the users table"}
+
+GET /db/users?sleeping=true
+# Response (200): "Wake up! This endpoint is disabled during sleep mode."
+```
+
+### Conditional Logic with `conditional`
+
+Use `conditional` to branch on the parameter's value. Each branch can lead to a `sql` fragment, a `response`, or an `action`.
+
+```yaml
+query_params:
+  - enrolled:
+      conditional:
+          true:
+              sql: enrolled = true       # adds to WHERE clause
+          false:
+              sql: enrolled = false
+          pending:
+              response:
+                  message: "Pending users cannot be queried"
+                  action: "Contact admin"
+          default:
+              response: "Unknown enrollment status"
+```
+
+```bash
+GET /db/users?enrolled=true
+# SQL: SELECT * FROM users WHERE enrolled = true
+
+GET /db/users?enrolled=pending
+# Response (200): {"message": "Pending users cannot be queried", "action": "Contact admin"}
+
+GET /db/users?enrolled=xyz
+# Response (200): "Unknown enrollment status"
+```
+
+### Complete Example
+
+Combining all parameter types in a single route:
+
+```yaml
+name: my_database
+tables:
+  users: s3://bucket/users.parquet
+
+routes:
+  - route: users/search
+    sql: SELECT * FROM [[users]]
+    query_params:
+      # WHERE clause filters
+      - name:
+          sql: name ILIKE '%{{name}}%'
+      - age_min:
+          sql: age >= {{age_min}}
+      - age_max:
+          sql: age <= {{age_max}}
+      - department:
+          sql: department = '{{department}}'
+      # Sorting and pagination (sql_append)
+      - sort:
+          sql_append: ORDER BY {{sort}} {{sort_direction}}
+          default: created_date
+      - sort_direction:
+          default: DESC
+      - limit:
+          sql_append: LIMIT {{limit}}
+          default: 50
+      - offset:
+          sql_append: OFFSET {{offset}}
+      # Direct response
+      - sleeping:
+          response: "Search is disabled during sleep mode."
+```
+
+```bash
+# Full search with filters, sorting, and pagination
+GET /my_database/users/search?name=john&age_min=21&age_max=65&sort=age&sort_direction=ASC&limit=20&offset=40
+# SQL: SELECT * FROM users
+#      WHERE name ILIKE '%john%' AND age >= 21 AND age <= 65
+#      ORDER BY age ASC LIMIT 20 OFFSET 40
+
+# Just defaults
+GET /my_database/users/search
+# SQL: SELECT * FROM users ORDER BY created_date DESC LIMIT 50
+
+# Direct response, no SQL
+GET /my_database/users/search?sleeping=true
+# Response: "Search is disabled during sleep mode."
+```
+
+### Processing Order
+
+Parameters are processed in this order (first match wins for early returns):
+
+1. `response` parameters — return immediately if parameter present
+2. `conditional` parameters — evaluate value, may return response or add SQL
+3. `required` parameters — return 400 if missing
+4. `sql` parameters — build WHERE clause fragments
+5. `sql_append` parameters — append post-WHERE clauses (ORDER BY, LIMIT, etc.)
+6. Execute final SQL query
+
+---
+
 # Using RouteMapper in Your Own Projects
 
 The core functionality is available as a standalone `RouteMapper` class that can be integrated into any web framework:

{api_dock-0.2.2 → api_dock-0.3.0}/README.md

@@ -14,6 +14,7 @@ API Dock (API(s) + (data)Base(s)/base-(for)-API(s)) a flexible API gateway that
   - [Main Configuration](#main-configuration-api_dock_configconfigyaml)
   - [Remote Configurations](#remote-configurations)
   - [SQL Database Support](#sql-database-support)
+  - [URL Query Parameters](#url-query-parameters)
 - [Using RouteMapper in Your Own Projects](#using-routemapper-in-your-own-projects)
   - [Basic Integration](#basic-integration)
   - [Framework Examples](#framework-examples)
@@ -29,6 +30,7 @@ API Dock (API(s) + (data)Base(s)/base-(for)-API(s)) a flexible API gateway that
 - **YAML Configuration**: Simple, human-readable configuration files
 - **Access Control**: Define allowed/restricted routes per remote API
 - **Version Support**: Handle API versioning in URL paths
+- **URL Query Parameters**: Declarative query parameter support for database routes with filtering, sorting, pagination, conditional logic, and direct responses
 - **Flexibility**: Quickly launch FastAPI or Flask apps, or easily integrate into any existing framework
 
 ## Install
@@ -447,6 +449,216 @@ routes:
 
 ---
 
+## URL Query Parameters
+
+Database routes support declarative URL query parameters via the `query_params` section. This lets you add filtering, sorting, pagination, conditional logic, and direct responses — all driven by the URL query string.
+
+Routes without a `query_params` section work exactly as before (full backward compatibility).
+
+### Basic Filtering with `sql`
+
+Use `sql` to add WHERE clause fragments. Each fragment is joined with `AND`. Optional by default — only included if the parameter is in the URL.
+
+```yaml
+routes:
+  - route: users
+    sql: SELECT * FROM [[users]]
+    query_params:
+      - age:
+          sql: age = {{age}}            # optional — only if ?age= provided
+      - department:
+          sql: department = '{{department}}'
+      - height:
+          sql: height < {{height}}
+          default: 200                  # always included (uses 200 if not in URL)
+```
+
+```bash
+GET /db/users?age=25&department=engineering
+# SQL: SELECT * FROM users WHERE age = 25 AND height < 200 AND department = 'engineering'
+
+GET /db/users
+# SQL: SELECT * FROM users WHERE height < 200
+```
+
+### Sorting and Pagination with `sql_append`
+
+Use `sql_append` to append clauses *after* the WHERE clause — for `ORDER BY`, `LIMIT`, `OFFSET`, etc. Fragments are appended in the order they appear in the YAML config, so **the YAML order must match valid SQL order** (ORDER BY before LIMIT before OFFSET).
+
+`sql_append` templates can reference `{{variables}}` from other parameters, including **value-only parameters** — params that only have a `default` and exist solely to provide a variable for other templates.
+
+```yaml
+routes:
+  - route: users
+    sql: SELECT * FROM [[users]]
+    query_params:
+      # WHERE clause params
+      - department:
+          sql: department = '{{department}}'
+      # Post-WHERE params
+      - sort:
+          sql_append: ORDER BY {{sort}} {{sort_direction}}
+          default: created_date
+      - sort_direction:
+          default: DESC               # value-only param — feeds into sort's template
+      - limit:
+          sql_append: LIMIT {{limit}}
+          default: 50
+      - offset:
+          sql_append: OFFSET {{offset}}  # optional — only if ?offset= provided
+```
+
+```bash
+GET /db/users?department=engineering&sort=name&sort_direction=ASC&limit=10
+# SQL: SELECT * FROM users WHERE department = 'engineering' ORDER BY name ASC LIMIT 10
+
+GET /db/users
+# SQL: SELECT * FROM users ORDER BY created_date DESC LIMIT 50
+
+GET /db/users?limit=20&offset=40
+# SQL: SELECT * FROM users ORDER BY created_date DESC LIMIT 20 OFFSET 40
+```
+
+### Required Parameters
+
+Use `required: true` to return a `400` error if the parameter is missing. Optionally provide a custom error response with `missing_response`.
+
+```yaml
+query_params:
+  - report_type:
+      sql: report_type = {{report_type}}
+      required: true
+      missing_response:
+          error: "report_type is required"
+          valid_types: ["summary", "detailed"]
+          http_status: 400
+```
+
+```bash
+GET /db/reports
+# Response (400): {"error": "report_type is required", "valid_types": [...], "http_status": 400}
+```
+
+### Direct Responses with `response`
+
+Use `response` to return a fixed JSON or string response immediately when the parameter is present (no SQL is executed).
+
+```yaml
+query_params:
+  - debug:
+      response:
+          message: Debug mode enabled
+          info: "This endpoint queries the users table"
+  - sleeping:
+      response: "Wake up! This endpoint is disabled during sleep mode."
+```
+
+```bash
+GET /db/users?debug=anything
+# Response (200): {"message": "Debug mode enabled", "info": "This endpoint queries the users table"}
+
+GET /db/users?sleeping=true
+# Response (200): "Wake up! This endpoint is disabled during sleep mode."
+```
+
+### Conditional Logic with `conditional`
+
+Use `conditional` to branch on the parameter's value. Each branch can lead to a `sql` fragment, a `response`, or an `action`.
+
+```yaml
+query_params:
+  - enrolled:
+      conditional:
+          true:
+              sql: enrolled = true       # adds to WHERE clause
+          false:
+              sql: enrolled = false
+          pending:
+              response:
+                  message: "Pending users cannot be queried"
+                  action: "Contact admin"
+          default:
+              response: "Unknown enrollment status"
+```
+
+```bash
+GET /db/users?enrolled=true
+# SQL: SELECT * FROM users WHERE enrolled = true
+
+GET /db/users?enrolled=pending
+# Response (200): {"message": "Pending users cannot be queried", "action": "Contact admin"}
+
+GET /db/users?enrolled=xyz
+# Response (200): "Unknown enrollment status"
+```
+
+### Complete Example
+
+Combining all parameter types in a single route:
+
+```yaml
+name: my_database
+tables:
+  users: s3://bucket/users.parquet
+
+routes:
+  - route: users/search
+    sql: SELECT * FROM [[users]]
+    query_params:
+      # WHERE clause filters
+      - name:
+          sql: name ILIKE '%{{name}}%'
+      - age_min:
+          sql: age >= {{age_min}}
+      - age_max:
+          sql: age <= {{age_max}}
+      - department:
+          sql: department = '{{department}}'
+      # Sorting and pagination (sql_append)
+      - sort:
+          sql_append: ORDER BY {{sort}} {{sort_direction}}
+          default: created_date
+      - sort_direction:
+          default: DESC
+      - limit:
+          sql_append: LIMIT {{limit}}
+          default: 50
+      - offset:
+          sql_append: OFFSET {{offset}}
+      # Direct response
+      - sleeping:
+          response: "Search is disabled during sleep mode."
+```
+
+```bash
+# Full search with filters, sorting, and pagination
+GET /my_database/users/search?name=john&age_min=21&age_max=65&sort=age&sort_direction=ASC&limit=20&offset=40
+# SQL: SELECT * FROM users
+#      WHERE name ILIKE '%john%' AND age >= 21 AND age <= 65
+#      ORDER BY age ASC LIMIT 20 OFFSET 40
+
+# Just defaults
+GET /my_database/users/search
+# SQL: SELECT * FROM users ORDER BY created_date DESC LIMIT 50
+
+# Direct response, no SQL
+GET /my_database/users/search?sleeping=true
+# Response: "Search is disabled during sleep mode."
+```
+
+### Processing Order
+
+Parameters are processed in this order (first match wins for early returns):
+
+1. `response` parameters — return immediately if parameter present
+2. `conditional` parameters — evaluate value, may return response or add SQL
+3. `required` parameters — return 400 if missing
+4. `sql` parameters — build WHERE clause fragments
+5. `sql_append` parameters — append post-WHERE clauses (ORDER BY, LIMIT, etc.)
+6. Execute final SQL query
+
+---
+
 # Using RouteMapper in Your Own Projects
 
 The core functionality is available as a standalone `RouteMapper` class that can be integrated into any web framework:

{api_dock-0.2.2 → api_dock-0.3.0}/api_dock/config.py

@@ -390,6 +390,67 @@ def find_route_mapping(full_route: str, method: str, remote_config: Dict[str, An
     return None
 
 
+def filter_remote_query_params(
+    query_params: Dict[str, str],
+    route: str,
+    method: str,
+    remote_config: Dict[str, Any]
+) -> Dict[str, str]:
+    """Filter query parameters based on remote config settings.
+
+    Checks for a route-level query_params setting first, then falls back
+    to the top-level remote config query_params. If neither exists, all
+    params are passed through unchanged (backward compatible).
+
+    Args:
+        query_params: Original query parameters from the request.
+        route: The actual route path (e.g., "users/123").
+        method: HTTP method (e.g., "GET", "POST").
+        remote_config: Remote configuration dictionary.
+
+    Returns:
+        Filtered query parameters dictionary.
+    """
+    routes = remote_config.get("routes", [])
+
+    # Find matching route and its query_params setting
+    route_query_params_setting = None
+    for route_entry in routes:
+        if isinstance(route_entry, str):
+            if _route_matches_pattern(route, route_entry):
+                # String routes have no query_params setting
+                break
+        elif isinstance(route_entry, dict):
+            if _route_matches_pattern(route, route_entry, method):
+                route_query_params_setting = route_entry.get("query_params")
+                break
+
+    # Fall back to top-level setting if route has no query_params key
+    if route_query_params_setting is None:
+        setting = remote_config.get("query_params")
+    else:
+        setting = route_query_params_setting
+
+    # No setting anywhere → pass all params through (backward compatible)
+    if setting is None:
+        return query_params
+
+    # True → all params
+    if setting is True:
+        return query_params
+
+    # False → no params
+    if setting is False:
+        return {}
+
+    # List → whitelist filter
+    if isinstance(setting, list):
+        return {k: v for k, v in query_params.items() if k in setting}
+
+    # Unknown type → pass all through
+    return query_params
+
+
 #
 # INTERNAL
 #

{api_dock-0.2.2 → api_dock-0.3.0}/api_dock/database_config.py

@@ -132,6 +132,45 @@ def get_table_metadata(table_name: str, database_config: Dict[str, Any]) -> Dict
         return {}
 
 
+def merge_query_params(route_config: Dict[str, Any], database_config: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge top-level query_params into route config.
+
+    Top-level query_params from the database config are applied to every route.
+    Route-level params take precedence: if a route defines a param with the same
+    name as a top-level param, the route version wins. Non-overridden top-level
+    params are appended after route params.
+
+    Args:
+        route_config: Route configuration dictionary.
+        database_config: Database configuration dictionary (may contain top-level query_params).
+
+    Returns:
+        Route config dict with merged query_params. Returns original route_config
+        if no top-level query_params exist.
+    """
+    top_level = database_config.get("query_params", [])
+    if not top_level:
+        return route_config
+
+    route_params = route_config.get("query_params", [])
+
+    # Get names already defined at route level
+    route_param_names = set()
+    for item in route_params:
+        if isinstance(item, dict) and len(item) == 1:
+            route_param_names.add(next(iter(item)))
+
+    # Append non-overridden top-level params after route params
+    merged = list(route_params)
+    for item in top_level:
+        if isinstance(item, dict) and len(item) == 1:
+            name = next(iter(item))
+            if name not in route_param_names:
+                merged.append(item)
+
+    return {**route_config, "query_params": merged}
+
+
 def get_named_query(query_name: str, database_config: Dict[str, Any]) -> Optional[str]:
     """Get a named query from database configuration.
 
@@ -239,6 +278,77 @@ def find_database_route(path: str, database_config: Dict[str, Any]) -> Optional[
     return None
 
 
+def validate_route_config(route_config: Dict[str, Any]) -> bool:
+    """Validate route configuration with new declarative parameter format.
+
+    Args:
+        route_config: Route configuration dictionary.
+
+    Returns:
+        True if configuration is valid, False otherwise.
+    """
+    # Validate basic route structure
+    if not isinstance(route_config, dict):
+        return False
+
+    # Check for required route field
+    if 'route' not in route_config:
+        return False
+
+    # Validate query_params structure if present
+    if 'query_params' in route_config:
+        query_params = route_config['query_params']
+        if not isinstance(query_params, list):
+            return False
+
+        for param_item in query_params:
+            if not isinstance(param_item, dict):
+                return False
+
+            # Each parameter should have exactly one key (the parameter name)
+            if len(param_item) != 1:
+                return False
+
+            param_name, param_config = next(iter(param_item.items()))
+
+            # Validate parameter configuration structure
+            if not isinstance(param_config, dict):
+                return False
+
+            # Check for valid configuration keys
+            valid_keys = {'sql', 'sql_append', 'response', 'conditional', 'action', 'required', 'default', 'missing_response'}
+            if not any(key in param_config for key in valid_keys):
+                return False
+
+            # Validate conditional structure if present
+            if 'conditional' in param_config:
+                conditional = param_config['conditional']
+                if not isinstance(conditional, dict):
+                    return False
+
+                # Each conditional value should have sql, response, or action
+                for condition_key, condition_config in conditional.items():
+                    if not isinstance(condition_config, dict):
+                        return False
+                    valid_condition_keys = {'sql', 'response', 'action'}
+                    if not any(key in condition_config for key in valid_condition_keys):
+                        return False
+
+            # Validate action structure if present
+            if 'action' in param_config:
+                action = param_config['action']
+                if not isinstance(action, (str, dict)):
+                    return False
+
+            # Validate missing_response structure if present
+            if 'missing_response' in param_config:
+                missing_response = param_config['missing_response']
+                if not isinstance(missing_response, dict):
+                    return False
+
+    return True
+
+
 #
 # INTERNAL
 #

{api_dock-0.2.2 → api_dock-0.3.0}/api_dock/fast_api.py

@@ -106,7 +106,8 @@ def _add_remote_routes(app: FastAPI, route_mapper: RouteMapper) -> None:
             # Handle as database route
             success, response_data, status_code, error_message = await route_mapper.map_database_route(
                 database_name=remote_name,
-                path=path
+                path=path,
+                query_params=dict(request.query_params)
             )
         else:
             # Handle as remote API route

{api_dock-0.2.2 → api_dock-0.3.0}/api_dock/flask_api.py

@@ -101,7 +101,8 @@ def _add_remote_routes(app: Flask, route_mapper: RouteMapper) -> None:
             success, response_data, status_code, error_message = asyncio.run(
                 route_mapper.map_database_route(
                     database_name=remote_name,
-                    path=""
+                    path="",
+                    query_params=dict(request.args)
                 )
             )
         else:
@@ -145,7 +146,8 @@ def _add_remote_routes(app: Flask, route_mapper: RouteMapper) -> None:
             success, response_data, status_code, error_message = asyncio.run(
                 route_mapper.map_database_route(
                     database_name=remote_name,
-                    path=path
+                    path=path,
+                    query_params=dict(request.args)
                 )
             )
         else: