Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

UN-2190 [MISC] Auto-capture execution ID in the API deployment Postman collection (#2031)

Athul8218164826eb
diff --git a/backend/api_v2/postman_collection/constants.py b/backend/api_v2/postman_collection/constants.py
index 7bcbe988e..117bcad98 100644
--- a/backend/api_v2/postman_collection/constants.py
+++ b/backend/api_v2/postman_collection/constants.py
@@ -6,4 +6,8 @@ class CollectionKey:
EXECUTE_PIPELINE_API_KEY = "Process pipeline"
STATUS_API_KEY = "Execution status"
STATUS_EXEC_ID_DEFAULT = "REPLACE_WITH_EXECUTION_ID"
+ EXEC_ID_VARIABLE_NAME = "execution_id"
+ # Derive the Postman variable reference from the variable name so the two
+ # can never drift apart (-> "{{execution_id}}").
+ STATUS_EXEC_ID_VARIABLE = f"{{{{{EXEC_ID_VARIABLE_NAME}}}}}"
AUTH_QUERY_PARAM_DEFAULT = "REPLACE_WITH_API_KEY"
diff --git a/backend/api_v2/postman_collection/dto.py b/backend/api_v2/postman_collection/dto.py
index 17a6865ee..1118af3df 100644
--- a/backend/api_v2/postman_collection/dto.py
+++ b/backend/api_v2/postman_collection/dto.py
@@ -1,6 +1,6 @@
from abc import ABC, abstractmethod
from dataclasses import asdict, dataclass, field
-from typing import Any
+from typing import Any, Literal
from urllib.parse import urlencode, urljoin
from django.conf import settings
@@ -18,6 +18,24 @@ class HeaderItem:
value: str
+@dataclass
+class ScriptItem:
+ exec: list[str]
+ type: Literal["text/javascript"] = "text/javascript"
+
+
+@dataclass
+class EventItem:
+ listen: Literal["prerequest", "test"]
+ script: ScriptItem
+
+
+@dataclass
+class VariableItem:
+ key: str
+ value: str
+
+
@dataclass
class FormDataItem:
key: str
@@ -55,6 +73,7 @@ class RequestItem:
class PostmanItem:
name: str
request: RequestItem
+ event: list[EventItem] = field(default_factory=list)
@dataclass
@@ -69,6 +88,12 @@ class APIBase(ABC):
def get_form_data_items(self) -> list[FormDataItem]:
pass
+ def get_collection_variables(self) -> list[VariableItem]:
+ """Collection-level variables; only needed when a request
+ references them.
+ """
+ return []
+
@abstractmethod
def get_api_endpoint(self) -> str:
pass
@@ -137,20 +162,61 @@ class APIDeploymentDto(APIBase):
def _get_status_api_request(self) -> RequestItem:
header_list = [HeaderItem(key="Authorization", value=f"Bearer {self.api_key}")]
status_query_param = {
- "execution_id": CollectionKey.STATUS_EXEC_ID_DEFAULT,
+ "execution_id": CollectionKey.STATUS_EXEC_ID_VARIABLE,
ApiExecution.INCLUDE_METADATA: "False",
ApiExecution.INCLUDE_METRICS: "False",
}
- status_query_str = urlencode(status_query_param)
+ # Keep {{...}} unescaped so Postman resolves the collection variable
+ status_query_str = urlencode(status_query_param, safe="{}")
abs_api_endpoint = urljoin(settings.WEB_APP_ORIGIN_URL, self.api_endpoint)
status_url = urljoin(abs_api_endpoint, "?" + status_query_str)
return RequestItem(method=HTTPMethod.GET, header=header_list, url=status_url)
+ def get_collection_variables(self) -> list[VariableItem]:
+ return [
+ VariableItem(
+ key=CollectionKey.EXEC_ID_VARIABLE_NAME,
+ value=CollectionKey.STATUS_EXEC_ID_DEFAULT,
+ )
+ ]
+
+ def _get_execute_capture_event(self) -> EventItem:
+ """Post-response script that stores the execution_id from the execute
+ response into a collection variable, so the status request can use it
+ without manual copy-pasting.
+
+ This is Postman's ``test`` hook (the emitted event uses
+ ``listen="test"``). It assumes the execute response shape
+ ``{"message": {"execution_id": ...}}``; if the body is non-JSON or
+ lacks that field it captures nothing and resets the variable to the
+ default sentinel so a stale id from a previous run is never reused.
+ """
+ return EventItem(
+ listen="test",
+ script=ScriptItem(
+ exec=[
+ "let response = null;",
+ "try {",
+ " response = pm.response.json();",
+ "} catch (error) {",
+ " // Non-JSON response (e.g. gateway error); nothing to capture",
+ "}",
+ "if (response && response.message && response.message.execution_id) {", # noqa: E501
+ f' pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}", response.message.execution_id);', # noqa: E501
+ "} else {",
+ f' pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}", "{CollectionKey.STATUS_EXEC_ID_DEFAULT}");', # noqa: E501
+ ' console.warn("No execution_id in execute response; not reusing a stale value. Status:", pm.response.code);', # noqa: E501
+ "}",
+ ]
+ ),
+ )
+
def get_postman_items(self) -> list[PostmanItem]:
postman_item_list = [
PostmanItem(
name=CollectionKey.EXECUTE_API_KEY,
request=self.get_create_api_request(),
+ event=[self._get_execute_capture_event()],
),
PostmanItem(
name=CollectionKey.STATUS_API_KEY,
@@ -192,6 +258,7 @@ class PipelineDto(APIBase):
class PostmanCollection:
info: PostmanInfo
item: list[PostmanItem] = field(default_factory=list)
+ variable: list[VariableItem] = field(default_factory=list)
@classmethod
def create(
@@ -228,7 +295,11 @@ class PostmanCollection:
)
postman_info: PostmanInfo = data_object.get_postman_info()
postman_item_list = data_object.get_postman_items()
- return cls(info=postman_info, item=postman_item_list)
+ return cls(
+ info=postman_info,
+ item=postman_item_list,
+ variable=data_object.get_collection_variables(),
+ )
def to_dict(self) -> dict[str, Any]:
"""Convert PostmanCollection instance to a dict.
@@ -237,4 +308,9 @@ class PostmanCollection:
dict[str, Any]: PostmanCollection as a dict
"""
collection_dict = asdict(self)
+ # Omit empty event blocks; items without scripts (e.g. pipelines)
+ # should not carry an "event" key at all.
+ for item in collection_dict.get("item", []):
+ if not item.get("event"):
+ item.pop("event", None)
return collection_dict
diff --git a/backend/api_v2/postman_collection/tests/__init__.py b/backend/api_v2/postman_collection/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/backend/api_v2/postman_collection/tests/test_dto.py b/backend/api_v2/postman_collection/tests/test_dto.py
new file mode 100644
index 000000000..b05048fb6
--- /dev/null
+++ b/backend/api_v2/postman_collection/tests/test_dto.py
@@ -0,0 +1,154 @@
+"""Regression tests for api_v2.postman_collection.dto — the builder that
+turns an API deployment or pipeline into a Postman v2.1 collection.
+
+UN-2190: the execute request gained a post-response capture script and the
+status request reuses the captured ``execution_id`` collection variable.
+These tests pin the contract so a refactor can't reopen the gaps the
+review flagged: the null-event strip, the variable/URL/JS all referencing
+the SAME constant, and the status URL keeping ``{{execution_id}}`` literal
+(not percent-encoded).
+
+The DTOs are constructed directly (no DB) and only ``WEB_APP_ORIGIN_URL``
+is overridden, so the suite is cheap and needs no fixtures.
+"""
+
+from __future__ import annotations
+
+import pytest
+from django.test import override_settings
+
+from api_v2.postman_collection.constants import CollectionKey
+from api_v2.postman_collection.dto import (
+ APIDeploymentDto,
+ PipelineDto,
+ PostmanCollection,
+)
+
+WEB_APP_ORIGIN_URL = "https://example.unstract.com"
+API_ENDPOINT = "deployment/api/org/my-api/"
+API_KEY = "test-api-key"
+
+
+def _api_deployment_dto() -> APIDeploymentDto:
+ return APIDeploymentDto(
+ display_name="My API",
+ description="An API deployment",
+ api_endpoint=API_ENDPOINT,
+ api_key=API_KEY,
+ )
+
+
+def _pipeline_dto() -> PipelineDto:
+ return PipelineDto(
+ pipeline_name="My Pipeline",
+ api_endpoint=API_ENDPOINT,
+ api_key=API_KEY,
+ )
+
+
+def _build_dict(data_object) -> dict:
+ """Mirror PostmanCollection.create without touching the DB.
+
+ Pins WEB_APP_ORIGIN_URL so URL building is deterministic regardless of
+ the ambient test settings.
+ """
+ with override_settings(WEB_APP_ORIGIN_URL=WEB_APP_ORIGIN_URL):
+ collection = PostmanCollection(
+ info=data_object.get_postman_info(),
+ item=data_object.get_postman_items(),
+ variable=data_object.get_collection_variables(),
+ )
+ return collection.to_dict()
+
+
+def _item_by_name(collection_dict: dict, name: str) -> dict:
+ for item in collection_dict["item"]:
+ if item["name"] == name:
+ return item
+ raise AssertionError(f"item {name!r} not found in collection")
+
+
+class TestApiDeploymentCollection:
+ def test_execute_item_keeps_populated_event(self) -> None:
+ """to_dict keeps the populated execute event and its capture script."""
+ collection_dict = _build_dict(_api_deployment_dto())
+ execute_item = _item_by_name(collection_dict, CollectionKey.EXECUTE_API_KEY)
+
+ assert "event" in execute_item
+ assert execute_item["event"], "execute event must not be stripped"
+ script_lines = execute_item["event"][0]["script"]["exec"]
+ joined = "\n".join(script_lines)
+ # The capture must target the same constant the variable/URL use.
+ assert (
+ f'pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}"'
+ in joined
+ )
+
+ def test_capture_script_resets_on_missing_execution_id(self) -> None:
+ """The else branch resets to the sentinel so a stale id is never reused."""
+ collection_dict = _build_dict(_api_deployment_dto())
+ execute_item = _item_by_name(collection_dict, CollectionKey.EXECUTE_API_KEY)
+ joined = "\n".join(execute_item["event"][0]["script"]["exec"])
+
+ assert "else" in joined
+ assert (
+ f'pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}", '
+ f'"{CollectionKey.STATUS_EXEC_ID_DEFAULT}")' in joined
+ )
+ assert "console.warn" in joined
+
+ def test_status_item_has_no_event_key(self) -> None:
+ """The status request carries no scripts -> no 'event' key at all."""
+ collection_dict = _build_dict(_api_deployment_dto())
+ status_item = _item_by_name(collection_dict, CollectionKey.STATUS_API_KEY)
+ assert "event" not in status_item
+
+ def test_variable_array_references_the_constant(self) -> None:
+ """The collection 'variable' array exposes the exec-id variable."""
+ collection_dict = _build_dict(_api_deployment_dto())
+ variables = collection_dict["variable"]
+ assert any(
+ v["key"] == CollectionKey.EXEC_ID_VARIABLE_NAME for v in variables
+ )
+
+ def test_status_url_keeps_unencoded_variable_reference(self) -> None:
+ """Status URL keeps execution_id={{execution_id}} literal, not %7B-encoded."""
+ collection_dict = _build_dict(_api_deployment_dto())
+ status_item = _item_by_name(collection_dict, CollectionKey.STATUS_API_KEY)
+ url = status_item["request"]["url"]
+
+ assert (
+ f"{CollectionKey.EXEC_ID_VARIABLE_NAME}="
+ f"{CollectionKey.STATUS_EXEC_ID_VARIABLE}" in url
+ )
+ assert "%7B" not in url and "%7D" not in url
+
+
+class TestCollectionShapeRegression:
+ def test_pipeline_carries_no_event_and_empty_variable(self) -> None:
+ """PipelineDto: no scripts and no collection variables."""
+ collection_dict = _build_dict(_pipeline_dto())
+ assert collection_dict["variable"] == []
+ for item in collection_dict["item"]:
+ assert "event" not in item
+
+ def test_api_deployment_carries_event_and_variable(self) -> None:
+ """APIDeploymentDto: execute event present and variable populated."""
+ collection_dict = _build_dict(_api_deployment_dto())
+ execute_item = _item_by_name(collection_dict, CollectionKey.EXECUTE_API_KEY)
+ assert execute_item.get("event")
+ assert collection_dict["variable"], "api deployment must expose variables"
+
+
+class TestConstantCoupling:
+ def test_status_variable_derived_from_name(self) -> None:
+ """STATUS_EXEC_ID_VARIABLE must be the {{...}} form of the var name."""
+ assert (
+ CollectionKey.STATUS_EXEC_ID_VARIABLE
+ == f"{{{{{CollectionKey.EXEC_ID_VARIABLE_NAME}}}}}"
+ )
+ assert CollectionKey.STATUS_EXEC_ID_VARIABLE == "{{execution_id}}"
+
+
+if __name__ == "__main__": # pragma: no cover
+ raise SystemExit(pytest.main([__file__, "-q"]))
diff --git a/backend/api_v2/serializers.py b/backend/api_v2/serializers.py
index 282adc8a4..58bcd8c17 100644
--- a/backend/api_v2/serializers.py
+++ b/backend/api_v2/serializers.py
@@ -523,6 +523,7 @@ class DeploymentResponseSerializer(Serializer):
class APIExecutionResponseSerializer(Serializer):
+ execution_id = CharField()
execution_status = CharField()
status_api = CharField()
error = CharField()