api-dock 0.6.0__tar.gz → 0.7.1__tar.gz

{api_dock-0.6.0 → api_dock-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.6.0
+Version: 0.7.1
 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-Expression: BSD-3-Clause
@@ -218,6 +218,7 @@ remotes:
 settings:
   add_trailing_slash: true              # Auto-add trailing slash to paths (default: true)
   follow_protocol_downgrades: false     # Allow HTTPS->HTTP redirects (default: false)
+  timeout: 10                           # Upstream request timeout in seconds (default: 10)
 ```
 
 ### HTTP behavior Settings
@@ -228,6 +229,8 @@ The optional `settings` section controls HTTP behavior:
 
 - **`follow_protocol_downgrades`** (default: `false`): Control how HTTP redirects are handled. When `false` (recommended), HTTPS→HTTP redirects are blocked for security. When `true`, allows following redirects that downgrade from HTTPS to HTTP (not recommended for production).
 
+- **`timeout`** (default: `10`): Upstream request timeout in seconds, applied to both the streaming and buffered proxy paths. Raise it for slow upstreams (e.g. large aggregation queries) that would otherwise return a 502 on timeout. Set to `null` or `false` to disable the timeout entirely (not recommended — a stalled upstream can hold the connection open indefinitely).
+
 ---
 
 ## Remote Configurations
@@ -463,6 +466,34 @@ GET /db/users
 # SQL: SELECT * FROM users WHERE height < 200
 ```
 
+### Repeated Parameters with `multivalue_sql`
+
+A query parameter key can appear more than once in the URL (e.g. `?recording_id=1&recording_id=4`). Add a `multivalue_sql` template alongside `sql` to handle this: when **more than one** value is passed for the key, `multivalue_sql` is used instead of `sql`, and `{{param}}` expands to a parenthesized, quote-escaped SQL value list suitable for an `IN` clause.
+
+Behavior is unchanged when `multivalue_sql` is absent, and when only a single value is passed the normal `sql` template is used.
+
+```yaml
+routes:
+  - route: detections
+    sql: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording_id:
+          sql: "[[detections]].recording_id = {{recording_id}}"            # single value
+          multivalue_sql: "[[detections]].recording_id IN {{recording_id}}"  # 2+ values
+      - scientific_name:
+          sql: "[[detections]].scientific_name = '{{scientific_name}}'"
+```
+
+```bash
+GET /db/detections?recording_id=4&scientific_name=Gryllus%20fultoni
+# SQL: SELECT detections.* FROM detections
+#      WHERE detections.recording_id = '4' AND detections.scientific_name = 'Gryllus fultoni'
+
+GET /db/detections?recording_id=4&recording_id=1&scientific_name=Gryllus%20fultoni
+# SQL: SELECT detections.* FROM detections
+#      WHERE detections.recording_id IN ('4', '1') AND detections.scientific_name = 'Gryllus fultoni'
+```
+
 ### 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).
@@ -641,6 +672,125 @@ Parameters are processed in this order (first match wins for early returns):
 
 ---
 
+## Conditional SQL Selection
+
+Some routes need a *different* base query depending on the request — for example, `?count=true` should return a species histogram (`SELECT … COUNT(*) … GROUP BY …`) rather than rows. `sql_append` can't help (it only adds trailing clauses), and a second `route:` can't either (the path is identical). For this, a route's `sql` may be a **rule list** instead of a string: a first-match-wins decision tree that picks the base query from the presence and value of path, query, and cookie params.
+
+Everything downstream is unchanged: the selected base composes with `query_params` WHERE-fragments and `sql_append` exactly as a plain `sql:` string does.
+
+### The histogram example
+
+```yaml
+routes:
+  - route: detections
+    sql:
+      # ?count=<truthy>  → species histogram
+      - when: count
+        then:
+          sql: >
+            SELECT [[detections]].common_name, [[detections]].scientific_name,
+                   COUNT(*) AS count
+            FROM [[detections]]
+          sql_append: GROUP BY [[detections]].common_name, [[detections]].scientific_name
+      # otherwise → detection rows
+      - else: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording:
+          sql: "[[detections]].recording_id = {{recording}}"
+          multivalue_sql: "[[detections]].recording_id IN {{recording}}"
+      - limit:
+          sql_append: LIMIT {{limit}}          # applies in BOTH modes
+```
+
+```bash
+GET /db/detections?recording=1&count=true
+# SELECT detections.common_name, detections.scientific_name, COUNT(*) AS count
+#   FROM detections WHERE detections.recording_id = '1'
+#   GROUP BY detections.common_name, detections.scientific_name
+
+GET /db/detections?recording=1
+# SELECT detections.* FROM detections WHERE detections.recording_id = '1'
+```
+
+Note the pipeline order: the selected branch's `sql_append` (the `GROUP BY`) is applied **before** route-level `sql_append` (the shared `LIMIT`), so SQL clause order stays valid.
+
+### Rule forms
+
+A `sql` list contains rules evaluated top to bottom; the **first match wins**. Each rule's payload (an *sql node*) is a SQL string, a leaf object `{sql, sql_append}`, or a nested rule list.
+
+```yaml
+sql:
+  - when: count                       # fires when `count` is truthy (shorthand for equals: _truthy)
+    then: <sql node>
+
+  - when: mode
+    equals: 'true'                    # fires only when mode == "true" (case-insensitive)
+    then: <sql node>
+
+  - when: format                      # value map: different SQL per value
+    match:
+      species: <sql node>             # ?format=species
+      recording: <sql node>           # ?format=recording
+      _truthy: <sql node>             # any other truthy value
+      _default: <sql node>            # any present value not matched above
+
+  - when: [count, recording]          # list: fires when ALL are truthy (AND)
+    then: <sql node>
+
+  - when: [count, something_else]     # list + positional case list
+    match:
+      - values: [_any, x]             # something_else == x, count anything
+        then: <sql node>
+      - values: [_truthy, _absent]    # count truthy AND something_else not passed
+        then: <sql node>
+      - default: <sql node>
+
+  - else: <sql node>                  # default (a trailing bare string works too)
+```
+
+Nesting works because a payload can itself be a rule list:
+
+```yaml
+sql:
+  - when: some_value
+    match:
+      '4':
+        - when: count
+          then: <sql for value 4 with count>
+        - else: <sql for value 4>
+      _default: <sql for other values>
+  - else: <base sql>
+```
+
+### Value specs
+
+| spec | matches when the param… |
+|---|---|
+| `'literal'` (`'4'`, `'true'`) | is present and equals it (case-insensitive) |
+| `_truthy` / `_falsy` | present, and value is / isn't in `{"", "0", "false", "no", "off", "null", "none"}` |
+| `_present` / `_absent` | exists / does not exist |
+| `_any` | wildcard — present or absent (used for a position in a case list) |
+| `_default` | catch-all for any *present* value (value maps only) |
+
+In a single-param `match:` map, precedence is order-independent: exact literal > `_falsy`/`_truthy` > `_present`/`_absent` > `_default`. In a positional case list, cases match strictly top-to-bottom.
+
+### No match → URL error
+
+If no rule matches and there is no default (`else`, a trailing bare string, or a `_default`/`default` catch-all), the request returns a **400** with `{"error": "No matching query configuration for the given parameters", "http_status": 400}`. Customize it with a terminal `no_match` rule:
+
+```yaml
+sql:
+  - when: recording
+    then: SELECT [[detections]].* FROM [[detections]] WHERE recording_id = {{recording}}
+  - no_match:
+      error: "recording is required, or pass count=true for a histogram"
+      http_status: 400
+```
+
+Cookies participate via the `cookies.<name>` key (e.g. `when: cookies.role`, `equals: admin`).
+
+---
+
 # CLI
 
 ## Commands
@@ -1170,8 +1320,6 @@ pixi run python scripts/hello_world.py
 
 ---
 
----
-
 # Development
 
 ## Publishing a Release
@@ -1183,11 +1331,11 @@ pixi run python scripts/hello_world.py
 
 # 2. Commit everything
 git add -A
-git commit -m "v0.6.0: proxy passthrough fixes, cookie injection"
+git commit -m "v0.6.1: stream proxy responses (fix large-response 502 + content-encoding)"
 
 # 3. Tag and push
-git tag v0.6.0
-git push origin main v0.6.0
+git tag v0.6.1
+git push origin main v0.6.1
 
 # 4. Build the wheel (requires the `dev` pixi environment)
 rm -rf dist/
@@ -1197,21 +1345,19 @@ pixi run -e dev python -m build --wheel
 ls dist/*.whl
 
 # 5. Create GitHub release with the wheel attached
-gh release create v0.6.0 dist/api_dock-0.6.0-py3-none-any.whl \
-    --title "v0.6.0" --notes "$(cat <<'EOF'
+gh release create v0.6.1 dist/api_dock-0.6.1-py3-none-any.whl \
+    --title "v0.6.1" --notes "$(cat <<'EOF'
 * new features
-    - Cookie injection: dict entries in the `cookies` list inject server-side cookies into upstream requests, with `env:MY_VAR` env var support and literal value support
+    - Remote proxy responses are now streamed (FastAPI) — upstream bytes are piped to the client as they arrive instead of being buffered fully in memory
+    - New `timeout` setting (default 10s) for the upstream request; set to `null`/`false` to disable
 * bug fixes
-    - Binary responses (image, audio) no longer corrupted — raw bytes passed through with correct content-type
-    - 3xx redirects returned to client when `follow_redirects: false` (previously followed internally, doubling egress)
-    - Upstream response headers (Cache-Control, ETag, Last-Modified, etc.) now forwarded to client
-    - Upstream 4xx/5xx error bodies passed through verbatim (previously wrapped/swallowed)
-    - JSON responses no longer re-serialized — raw bytes returned as-is, preserving exact upstream payload
+    - Large upstream responses no longer return 502 — streamed via `StreamingResponse` instead of reading the whole body into memory
+    - `Content-Encoding` (gzip/br/deflate) is now preserved on compressed responses — raw bytes are streamed via `aiter_raw()` so the header stays valid and the client can decompress
+    - Slow upstreams (e.g. large aggregation queries) no longer 502 at httpx's hardcoded 5s default — the timeout is now configurable via the `timeout` setting
 * cleanup / other improvements
-    - Added `ProxyResponse` typed dataclass as the return contract for `map_route()` and `map_database_route()`
-    - Added test suite (38 tests covering proxy pipeline and cookie injection)
-    - Removed broken root `__init__.py` that caused pytest import conflicts
-    - Bumped cryptography dependency to >=48.0.0,<49.0.0
+    - Added `PreparedRequest` dataclass and split route validation/resolution into `RouteMapper.prepare_remote_request()`; the FastAPI adapter issues the streaming HTTP call
+    - `map_route()` (buffered) retained for the Flask/sync path
+    - Added streaming test coverage (`TestStreamUpstream`, plus `prepare_remote_request` and streaming-header tests) — 53 tests total
 EOF
 )"
 

{api_dock-0.6.0 → api_dock-0.7.1}/README.md

@@ -179,6 +179,7 @@ remotes:
 settings:
   add_trailing_slash: true              # Auto-add trailing slash to paths (default: true)
   follow_protocol_downgrades: false     # Allow HTTPS->HTTP redirects (default: false)
+  timeout: 10                           # Upstream request timeout in seconds (default: 10)
 ```
 
 ### HTTP behavior Settings
@@ -189,6 +190,8 @@ The optional `settings` section controls HTTP behavior:
 
 - **`follow_protocol_downgrades`** (default: `false`): Control how HTTP redirects are handled. When `false` (recommended), HTTPS→HTTP redirects are blocked for security. When `true`, allows following redirects that downgrade from HTTPS to HTTP (not recommended for production).
 
+- **`timeout`** (default: `10`): Upstream request timeout in seconds, applied to both the streaming and buffered proxy paths. Raise it for slow upstreams (e.g. large aggregation queries) that would otherwise return a 502 on timeout. Set to `null` or `false` to disable the timeout entirely (not recommended — a stalled upstream can hold the connection open indefinitely).
+
 ---
 
 ## Remote Configurations
@@ -424,6 +427,34 @@ GET /db/users
 # SQL: SELECT * FROM users WHERE height < 200
 ```
 
+### Repeated Parameters with `multivalue_sql`
+
+A query parameter key can appear more than once in the URL (e.g. `?recording_id=1&recording_id=4`). Add a `multivalue_sql` template alongside `sql` to handle this: when **more than one** value is passed for the key, `multivalue_sql` is used instead of `sql`, and `{{param}}` expands to a parenthesized, quote-escaped SQL value list suitable for an `IN` clause.
+
+Behavior is unchanged when `multivalue_sql` is absent, and when only a single value is passed the normal `sql` template is used.
+
+```yaml
+routes:
+  - route: detections
+    sql: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording_id:
+          sql: "[[detections]].recording_id = {{recording_id}}"            # single value
+          multivalue_sql: "[[detections]].recording_id IN {{recording_id}}"  # 2+ values
+      - scientific_name:
+          sql: "[[detections]].scientific_name = '{{scientific_name}}'"
+```
+
+```bash
+GET /db/detections?recording_id=4&scientific_name=Gryllus%20fultoni
+# SQL: SELECT detections.* FROM detections
+#      WHERE detections.recording_id = '4' AND detections.scientific_name = 'Gryllus fultoni'
+
+GET /db/detections?recording_id=4&recording_id=1&scientific_name=Gryllus%20fultoni
+# SQL: SELECT detections.* FROM detections
+#      WHERE detections.recording_id IN ('4', '1') AND detections.scientific_name = 'Gryllus fultoni'
+```
+
 ### 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).
@@ -602,6 +633,125 @@ Parameters are processed in this order (first match wins for early returns):
 
 ---
 
+## Conditional SQL Selection
+
+Some routes need a *different* base query depending on the request — for example, `?count=true` should return a species histogram (`SELECT … COUNT(*) … GROUP BY …`) rather than rows. `sql_append` can't help (it only adds trailing clauses), and a second `route:` can't either (the path is identical). For this, a route's `sql` may be a **rule list** instead of a string: a first-match-wins decision tree that picks the base query from the presence and value of path, query, and cookie params.
+
+Everything downstream is unchanged: the selected base composes with `query_params` WHERE-fragments and `sql_append` exactly as a plain `sql:` string does.
+
+### The histogram example
+
+```yaml
+routes:
+  - route: detections
+    sql:
+      # ?count=<truthy>  → species histogram
+      - when: count
+        then:
+          sql: >
+            SELECT [[detections]].common_name, [[detections]].scientific_name,
+                   COUNT(*) AS count
+            FROM [[detections]]
+          sql_append: GROUP BY [[detections]].common_name, [[detections]].scientific_name
+      # otherwise → detection rows
+      - else: SELECT [[detections]].* FROM [[detections]]
+    query_params:
+      - recording:
+          sql: "[[detections]].recording_id = {{recording}}"
+          multivalue_sql: "[[detections]].recording_id IN {{recording}}"
+      - limit:
+          sql_append: LIMIT {{limit}}          # applies in BOTH modes
+```
+
+```bash
+GET /db/detections?recording=1&count=true
+# SELECT detections.common_name, detections.scientific_name, COUNT(*) AS count
+#   FROM detections WHERE detections.recording_id = '1'
+#   GROUP BY detections.common_name, detections.scientific_name
+
+GET /db/detections?recording=1
+# SELECT detections.* FROM detections WHERE detections.recording_id = '1'
+```
+
+Note the pipeline order: the selected branch's `sql_append` (the `GROUP BY`) is applied **before** route-level `sql_append` (the shared `LIMIT`), so SQL clause order stays valid.
+
+### Rule forms
+
+A `sql` list contains rules evaluated top to bottom; the **first match wins**. Each rule's payload (an *sql node*) is a SQL string, a leaf object `{sql, sql_append}`, or a nested rule list.
+
+```yaml
+sql:
+  - when: count                       # fires when `count` is truthy (shorthand for equals: _truthy)
+    then: <sql node>
+
+  - when: mode
+    equals: 'true'                    # fires only when mode == "true" (case-insensitive)
+    then: <sql node>
+
+  - when: format                      # value map: different SQL per value
+    match:
+      species: <sql node>             # ?format=species
+      recording: <sql node>           # ?format=recording
+      _truthy: <sql node>             # any other truthy value
+      _default: <sql node>            # any present value not matched above
+
+  - when: [count, recording]          # list: fires when ALL are truthy (AND)
+    then: <sql node>
+
+  - when: [count, something_else]     # list + positional case list
+    match:
+      - values: [_any, x]             # something_else == x, count anything
+        then: <sql node>
+      - values: [_truthy, _absent]    # count truthy AND something_else not passed
+        then: <sql node>
+      - default: <sql node>
+
+  - else: <sql node>                  # default (a trailing bare string works too)
+```
+
+Nesting works because a payload can itself be a rule list:
+
+```yaml
+sql:
+  - when: some_value
+    match:
+      '4':
+        - when: count
+          then: <sql for value 4 with count>
+        - else: <sql for value 4>
+      _default: <sql for other values>
+  - else: <base sql>
+```
+
+### Value specs
+
+| spec | matches when the param… |
+|---|---|
+| `'literal'` (`'4'`, `'true'`) | is present and equals it (case-insensitive) |
+| `_truthy` / `_falsy` | present, and value is / isn't in `{"", "0", "false", "no", "off", "null", "none"}` |
+| `_present` / `_absent` | exists / does not exist |
+| `_any` | wildcard — present or absent (used for a position in a case list) |
+| `_default` | catch-all for any *present* value (value maps only) |
+
+In a single-param `match:` map, precedence is order-independent: exact literal > `_falsy`/`_truthy` > `_present`/`_absent` > `_default`. In a positional case list, cases match strictly top-to-bottom.
+
+### No match → URL error
+
+If no rule matches and there is no default (`else`, a trailing bare string, or a `_default`/`default` catch-all), the request returns a **400** with `{"error": "No matching query configuration for the given parameters", "http_status": 400}`. Customize it with a terminal `no_match` rule:
+
+```yaml
+sql:
+  - when: recording
+    then: SELECT [[detections]].* FROM [[detections]] WHERE recording_id = {{recording}}
+  - no_match:
+      error: "recording is required, or pass count=true for a histogram"
+      http_status: 400
+```
+
+Cookies participate via the `cookies.<name>` key (e.g. `when: cookies.role`, `equals: admin`).
+
+---
+
 # CLI
 
 ## Commands
@@ -1131,8 +1281,6 @@ pixi run python scripts/hello_world.py
 
 ---
 
----
-
 # Development
 
 ## Publishing a Release
@@ -1144,11 +1292,11 @@ pixi run python scripts/hello_world.py
 
 # 2. Commit everything
 git add -A
-git commit -m "v0.6.0: proxy passthrough fixes, cookie injection"
+git commit -m "v0.6.1: stream proxy responses (fix large-response 502 + content-encoding)"
 
 # 3. Tag and push
-git tag v0.6.0
-git push origin main v0.6.0
+git tag v0.6.1
+git push origin main v0.6.1
 
 # 4. Build the wheel (requires the `dev` pixi environment)
 rm -rf dist/
@@ -1158,21 +1306,19 @@ pixi run -e dev python -m build --wheel
 ls dist/*.whl
 
 # 5. Create GitHub release with the wheel attached
-gh release create v0.6.0 dist/api_dock-0.6.0-py3-none-any.whl \
-    --title "v0.6.0" --notes "$(cat <<'EOF'
+gh release create v0.6.1 dist/api_dock-0.6.1-py3-none-any.whl \
+    --title "v0.6.1" --notes "$(cat <<'EOF'
 * new features
-    - Cookie injection: dict entries in the `cookies` list inject server-side cookies into upstream requests, with `env:MY_VAR` env var support and literal value support
+    - Remote proxy responses are now streamed (FastAPI) — upstream bytes are piped to the client as they arrive instead of being buffered fully in memory
+    - New `timeout` setting (default 10s) for the upstream request; set to `null`/`false` to disable
 * bug fixes
-    - Binary responses (image, audio) no longer corrupted — raw bytes passed through with correct content-type
-    - 3xx redirects returned to client when `follow_redirects: false` (previously followed internally, doubling egress)
-    - Upstream response headers (Cache-Control, ETag, Last-Modified, etc.) now forwarded to client
-    - Upstream 4xx/5xx error bodies passed through verbatim (previously wrapped/swallowed)
-    - JSON responses no longer re-serialized — raw bytes returned as-is, preserving exact upstream payload
+    - Large upstream responses no longer return 502 — streamed via `StreamingResponse` instead of reading the whole body into memory
+    - `Content-Encoding` (gzip/br/deflate) is now preserved on compressed responses — raw bytes are streamed via `aiter_raw()` so the header stays valid and the client can decompress
+    - Slow upstreams (e.g. large aggregation queries) no longer 502 at httpx's hardcoded 5s default — the timeout is now configurable via the `timeout` setting
 * cleanup / other improvements
-    - Added `ProxyResponse` typed dataclass as the return contract for `map_route()` and `map_database_route()`
-    - Added test suite (38 tests covering proxy pipeline and cookie injection)
-    - Removed broken root `__init__.py` that caused pytest import conflicts
-    - Bumped cryptography dependency to >=48.0.0,<49.0.0
+    - Added `PreparedRequest` dataclass and split route validation/resolution into `RouteMapper.prepare_remote_request()`; the FastAPI adapter issues the streaming HTTP call
+    - `map_route()` (buffered) retained for the Flask/sync path
+    - Added streaming test coverage (`TestStreamUpstream`, plus `prepare_remote_request` and streaming-header tests) — 53 tests total
 EOF
 )"
 

{api_dock-0.6.0 → api_dock-0.7.1}/api_dock/config.py

@@ -670,25 +670,29 @@ def find_route_mapping(full_route: str, method: str, remote_config: Dict[str, An
 
 
 def filter_remote_query_params(
-    query_params: Dict[str, str],
+    query_params: Dict[str, Any],
     route: str,
     method: str,
     remote_config: Dict[str, Any]
-) -> Dict[str, str]:
+) -> Dict[str, Any]:
     """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).
 
+    Filtering is by key only, so values may be strings or lists of strings
+    (the latter forwarding repeated keys such as ?id=1&id=2 intact).
+
     Args:
-        query_params: Original query parameters from the request.
+        query_params: Original query parameters from the request. Values may be
+            strings or lists of strings.
         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.
+        Filtered query parameters dictionary (value types preserved).
     """
     routes = remote_config.get("routes", [])
 

{api_dock-0.6.0 → api_dock-0.7.1}/api_dock/database_config.py

@@ -295,6 +295,10 @@ def validate_route_config(route_config: Dict[str, Any]) -> bool:
     if 'route' not in route_config:
         return False
 
+    # The sql selector may be a plain string or a list of selector rules.
+    if 'sql' in route_config and not isinstance(route_config['sql'], (str, list)):
+        return False
+
     # Validate query_params structure if present
     if 'query_params' in route_config:
         query_params = route_config['query_params']

{api_dock-0.6.0 → api_dock-0.7.1}/api_dock/example_api_dock_config/config.yaml

@@ -14,6 +14,7 @@ databases:
 settings:
   add_trailing_slash: false   # Set true to auto-append trailing slash to proxied paths
   follow_redirects: true      # Set false to pass 3xx redirects through to the client
+  timeout: 10                 # Upstream request timeout (seconds); null/false to disable
 
 # Global route restrictions — applied to all remotes unless overridden per-remote.
 # Uncomment to block DELETE on every remote:

{api_dock-0.6.0 → api_dock-0.7.1}/api_dock/example_api_dock_config/databases/example_db.yaml

@@ -20,6 +20,13 @@ routes:
       - category:
           sql: "[[items]].category = '{{category}}'"
 
+      # Repeated param — add multivalue_sql to support ?id=1&id=2. When more than
+      # one value is passed, multivalue_sql is used and {{id}} expands to a
+      # parenthesized value list (e.g. ('1', '2')) for use with IN.
+      - id:
+          sql: "[[items]].id = {{id}}"
+          multivalue_sql: "[[items]].id IN {{id}}"
+
       # Sorting — sql_append clauses are appended after the WHERE clause in YAML order.
       - sort:
           sql_append: ORDER BY {{sort}} {{direction}}
@@ -73,3 +80,17 @@ routes:
 # - debug:
 #     response:
 #       message: "Debug mode — no query executed"
+
+# Conditional SQL selection — pick a different base query from a param's
+# presence/value. Here ?count=<truthy> returns a histogram; otherwise rows.
+# The selected base still composes with query_params (WHERE + sql_append).
+# - route: detections
+#   sql:
+#     - when: count
+#       then:
+#         sql: SELECT [[items]].category, COUNT(*) AS count FROM [[items]]
+#         sql_append: GROUP BY [[items]].category
+#     - else: SELECT [[items]].* FROM [[items]]
+#   query_params:
+#     - category:
+#         sql: "[[items]].category = '{{category}}'"