From 33cdc56404c8444c4dfcb438d5ab5e5dbebe47c5 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Thu, 9 Jul 2026 16:47:40 +0200 Subject: [PATCH 1/7] feat: add Cobuild support metadata --- custom-recipes/api-connect/Cobuild.md | 29 ++++++++++++++++++++++++++ custom-recipes/api-connect/recipe.json | 3 +++ 2 files changed, 32 insertions(+) create mode 100644 custom-recipes/api-connect/Cobuild.md diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md new file mode 100644 index 0000000..920478e --- /dev/null +++ b/custom-recipes/api-connect/Cobuild.md @@ -0,0 +1,29 @@ +# Cobuild guidance + +Use this recipe to call a REST API once for each row of the input dataset and write the extracted response to the output dataset. + +Roles: +- `input_A_role`: required input dataset containing the variables used in URL, header, query, body, and pagination templates. +- `api_output`: required output dataset for the API response rows. + +Core configuration: +- Set `endpoint_url` to the URL template. Dataset columns can be referenced as `{{column_name}}`. +- Set `http_method` to `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. +- Use `endpoint_query_string` for query parameters and `endpoint_headers` for headers. +- Use `parameter_columns` to expose input columns as template variables. +- Use `parameter_renamings` when column names should map to cleaner template variable names. +- Use `body_format`, `text_body`, or `key_value_body` for request bodies. `text_body` is visible for `RAW`; `key_value_body` is visible for `FORM_DATA` and `MULTIPART_FORM_DATA`. +- Set `extraction_key` when the response data is nested under a JSON key. Keep `raw_output=true` when the full response JSON should be kept. + +Authentication and presets: +- This recipe uses preset fields for credentials. Prefer an existing usable preset from the recipe definition. +- For the generic credential preset, keep `auth_type` null and set `credential` to the selected preset name from parameter set `credential`. +- For secure OAuth, set `auth_type=secure_oauth` and set `secure_oauth` to a preset from parameter set `secure-oauth`. +- For secure OAuth with refresh-token rotation, set `auth_type=secure_oauth_refresh_token_rotation` and set `secure_oauth_refresh_token_rotation` to a preset from parameter set `secure-oauth-refresh-token-rotation`. +- For secure basic auth, set `auth_type=secure_basic` and set `secure_basic` to a preset from parameter set `secure-basic`. +- Do not ask the user to paste preset secrets in chat. If no usable preset is available or selected, create the recipe skeleton, navigate to the recipe settings, and ask the user to select or create the preset there. + +Pagination: +- Keep `pagination_type=na` unless the API documentation requires pagination. +- For next-page pagination, set `next_page_url_key`, and set `is_next_page_url_relative` plus `next_page_url_base` when the returned next URL is relative. +- For offset or page pagination, set the visible key fields and define `extraction_key` when required by the API response shape. diff --git a/custom-recipes/api-connect/recipe.json b/custom-recipes/api-connect/recipe.json index f836ed9..c4793de 100644 --- a/custom-recipes/api-connect/recipe.json +++ b/custom-recipes/api-connect/recipe.json @@ -5,6 +5,9 @@ "icon": "icon-rocket" }, "kind": "PYTHON", + "cobuild": { + "supported": true + }, "selectableFromDataset": "input_A_role", "inputRoles": [ { From 9bad3804d256b27845fd6392c65e3971b4bcfaf3 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 21 Jul 2026 15:19:52 +0200 Subject: [PATCH 2/7] chore: streamline Cobuild guidance --- custom-recipes/api-connect/Cobuild.md | 38 +++++++++++---------------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index 920478e..b9c5bd4 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -1,29 +1,21 @@ # Cobuild guidance -Use this recipe to call a REST API once for each row of the input dataset and write the extracted response to the output dataset. +Role-specific behavior: +- `input_A_role` supplies one API call per row and the column values available to request templates. +- `api_output` collects the response rows extracted from those calls and any paginated responses. -Roles: -- `input_A_role`: required input dataset containing the variables used in URL, header, query, body, and pagination templates. -- `api_output`: required output dataset for the API response rows. +Request behavior: +- Columns selected in `parameter_columns` become `{{column_name}}` template variables across the URL, headers, query parameters, body, and pagination settings; `parameter_renamings` changes their template names. +- `should_use_user_secrets=true` also exposes the current user's Profile > My account > Other credentials as template variables. +- `body_format=RAW` uses `text_body`; `FORM_DATA` and `MULTIPART_FORM_DATA` use `key_value_body`. +- `auth_type=null` selects the generic `credential` preset path; each secure authentication type selects its corresponding preset field. -Core configuration: -- Set `endpoint_url` to the URL template. Dataset columns can be referenced as `{{column_name}}`. -- Set `http_method` to `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. -- Use `endpoint_query_string` for query parameters and `endpoint_headers` for headers. -- Use `parameter_columns` to expose input columns as template variables. -- Use `parameter_renamings` when column names should map to cleaner template variable names. -- Use `body_format`, `text_body`, or `key_value_body` for request bodies. `text_body` is visible for `RAW`; `key_value_body` is visible for `FORM_DATA` and `MULTIPART_FORM_DATA`. -- Set `extraction_key` when the response data is nested under a JSON key. Keep `raw_output=true` when the full response JSON should be kept. - -Authentication and presets: -- This recipe uses preset fields for credentials. Prefer an existing usable preset from the recipe definition. -- For the generic credential preset, keep `auth_type` null and set `credential` to the selected preset name from parameter set `credential`. -- For secure OAuth, set `auth_type=secure_oauth` and set `secure_oauth` to a preset from parameter set `secure-oauth`. -- For secure OAuth with refresh-token rotation, set `auth_type=secure_oauth_refresh_token_rotation` and set `secure_oauth_refresh_token_rotation` to a preset from parameter set `secure-oauth-refresh-token-rotation`. -- For secure basic auth, set `auth_type=secure_basic` and set `secure_basic` to a preset from parameter set `secure-basic`. -- Do not ask the user to paste preset secrets in chat. If no usable preset is available or selected, create the recipe skeleton, navigate to the recipe settings, and ask the user to select or create the preset there. +Response extraction: +- Use the dot-separated `extraction_key` when response rows are nested under a JSON path. +- Keep `raw_output=true` when each response item should be preserved as raw JSON instead of flattened into columns. Pagination: -- Keep `pagination_type=na` unless the API documentation requires pagination. -- For next-page pagination, set `next_page_url_key`, and set `is_next_page_url_relative` plus `next_page_url_base` when the returned next URL is relative. -- For offset or page pagination, set the visible key fields and define `extraction_key` when required by the API response shape. +- Select the pagination mechanism from the target API's documentation; do not infer one from the endpoint shape. +- For next-page pagination, `next_page_url_key` is the dot-separated response path containing the following request URL. When that URL is relative, enable `is_next_page_url_relative` and provide `next_page_url_base`. +- Page pagination requires `extraction_key` so the recipe can locate and count the returned data array. +- For offset and page pagination, `skip_key` is the query parameter carrying the next offset or page number. From de37547f68f20f8cc12d301ff587e9d555f16494 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Wed, 22 Jul 2026 15:17:11 +0200 Subject: [PATCH 3/7] chore: document automatic API key injection --- custom-recipes/api-connect/Cobuild.md | 1 + 1 file changed, 1 insertion(+) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index b9c5bd4..24b96bb 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -9,6 +9,7 @@ Request behavior: - `should_use_user_secrets=true` also exposes the current user's Profile > My account > Other credentials as template variables. - `body_format=RAW` uses `text_body`; `FORM_DATA` and `MULTIPART_FORM_DATA` use `key_value_body`. - `auth_type=null` selects the generic `credential` preset path; each secure authentication type selects its corresponding preset field. +- For API-key presets, API Connect automatically injects the key into either a request header or query parameter, as configured by the user in the preset. Response extraction: - Use the dot-separated `extraction_key` when response rows are nested under a JSON path. From 041876ba5adc9b6fee6388b229d31b64e8a5667f Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 4 Aug 2026 09:04:40 +0200 Subject: [PATCH 4/7] chore: refine API Connect Cobuild guidance --- custom-recipes/api-connect/Cobuild.md | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index 24b96bb..80f99f1 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -1,22 +1,9 @@ # Cobuild guidance -Role-specific behavior: -- `input_A_role` supplies one API call per row and the column values available to request templates. -- `api_output` collects the response rows extracted from those calls and any paginated responses. - -Request behavior: -- Columns selected in `parameter_columns` become `{{column_name}}` template variables across the URL, headers, query parameters, body, and pagination settings; `parameter_renamings` changes their template names. -- `should_use_user_secrets=true` also exposes the current user's Profile > My account > Other credentials as template variables. -- `body_format=RAW` uses `text_body`; `FORM_DATA` and `MULTIPART_FORM_DATA` use `key_value_body`. -- `auth_type=null` selects the generic `credential` preset path; each secure authentication type selects its corresponding preset field. -- For API-key presets, API Connect automatically injects the key into either a request header or query parameter, as configured by the user in the preset. - -Response extraction: +- API Connect performs one API call per input row and writes the extracted rows from each response, including paginated responses, to the output dataset. +- Always set `endpoint_url` and select at least one `parameter_columns` column. Selected columns become `{{column_name}}` template variables across request fields; `parameter_renamings` changes their template names. +- With `auth_type=null`, leave `credential` unset for an unauthenticated API; otherwise select a compatible generic credential preset. For a secure authentication type, select its corresponding visible preset. +- API Connect automatically injects an API-key preset into the header or query parameter configured by the user in that preset. Do not add the API key again to request fields. - Use the dot-separated `extraction_key` when response rows are nested under a JSON path. - Keep `raw_output=true` when each response item should be preserved as raw JSON instead of flattened into columns. - -Pagination: -- Select the pagination mechanism from the target API's documentation; do not infer one from the endpoint shape. -- For next-page pagination, `next_page_url_key` is the dot-separated response path containing the following request URL. When that URL is relative, enable `is_next_page_url_relative` and provide `next_page_url_base`. -- Page pagination requires `extraction_key` so the recipe can locate and count the returned data array. -- For offset and page pagination, `skip_key` is the query parameter carrying the next offset or page number. +- Select the pagination mechanism from the target API's documentation; do not infer one from the endpoint shape. Relative next-page URLs require `next_page_url_base`, page pagination requires `extraction_key`, and offset or page pagination requires `skip_key`. From 5247a8698d45a65c34a1ff93e28e521eb19a78a0 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 4 Aug 2026 09:13:40 +0200 Subject: [PATCH 5/7] chore: clarify API Connect preset guidance --- custom-recipes/api-connect/Cobuild.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index 80f99f1..c6d9d78 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -2,7 +2,7 @@ - API Connect performs one API call per input row and writes the extracted rows from each response, including paginated responses, to the output dataset. - Always set `endpoint_url` and select at least one `parameter_columns` column. Selected columns become `{{column_name}}` template variables across request fields; `parameter_renamings` changes their template names. -- With `auth_type=null`, leave `credential` unset for an unauthenticated API; otherwise select a compatible generic credential preset. For a secure authentication type, select its corresponding visible preset. +- `auth_type=null` supports either no authentication (`credential` unset) or a generic credential preset. A secure authentication type requires its corresponding visible preset. - API Connect automatically injects an API-key preset into the header or query parameter configured by the user in that preset. Do not add the API key again to request fields. - Use the dot-separated `extraction_key` when response rows are nested under a JSON path. - Keep `raw_output=true` when each response item should be preserved as raw JSON instead of flattened into columns. From 7338e4e7453cba2502b4c1e11b66726626dd7772 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Tue, 4 Aug 2026 10:39:50 +0200 Subject: [PATCH 6/7] chore: remove redundant Cobuild header --- custom-recipes/api-connect/Cobuild.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/custom-recipes/api-connect/Cobuild.md b/custom-recipes/api-connect/Cobuild.md index c6d9d78..5685154 100644 --- a/custom-recipes/api-connect/Cobuild.md +++ b/custom-recipes/api-connect/Cobuild.md @@ -1,5 +1,3 @@ -# Cobuild guidance - - API Connect performs one API call per input row and writes the extracted rows from each response, including paginated responses, to the output dataset. - Always set `endpoint_url` and select at least one `parameter_columns` column. Selected columns become `{{column_name}}` template variables across request fields; `parameter_renamings` changes their template names. - `auth_type=null` supports either no authentication (`credential` unset) or a generic credential preset. A secure authentication type requires its corresponding visible preset. From f18effad7e59e9daff11af03a9e1b8008c7dad61 Mon Sep 17 00:00:00 2001 From: Alexandre Magaud Date: Mon, 10 Aug 2026 11:50:56 +0200 Subject: [PATCH 7/7] chore: bump version to 1.5.0 --- CHANGELOG.md | 4 ++++ plugin.json | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0cf75e4..c44c5eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## [Version 1.5.0](https://github.com/dataiku/dss-plugin-api-connect/releases/tag/v1.5.0) - Feature - 2026-08 + +- Add Cobuild support to the API Connect recipe + ## [Version 1.4.2](https://github.com/dataiku/dss-plugin-api-connect/releases/tag/v1.4.2) - Bugfix - 2026-07-22 - Remove user's 'Other credentials' from recipe's logs diff --git a/plugin.json b/plugin.json index 43a5253..b9c9925 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "id": "api-connect", - "version": "1.4.2", + "version": "1.5.0", "meta": { "label": "API Connect", "description": "Retrieve data from any REST API",