Merge pull request #173 from telefonicaid/issue/get-compatibility

Issue `GET` compatibility

Author: fgalan

CHANGES_NEXT_RELEASE

@@ -0,0 +1 @@
+- Add: Pentaho CDA backward compatibility now supports browser-style `GET /plugin/cda/api/doQuery` with query params, including `outputType` (`json`, `csv`, `xls`) (#108)

doc/03_api.md

@@ -32,7 +32,7 @@
         -   [Delete DA](#delete-da-delete-visibilityfdasfdaiddasdaid)
     -   [Data operations](#data-operations)
         -   [Data query](#data-query-get-visibilityfdasfdaiddasdaiddata)
-        -   [Query (Pentaho CDA legacy support)](#query-post-plugincdaapidoquery-pentaho-cda-legacy-support)
+        -   [Query (Pentaho CDA legacy support)](#query-plugincdaapidoquery-pentaho-cda-legacy-support)
 -   [Navigation](#-navigation)
 
 ## Introduction
@@ -1733,7 +1733,7 @@ curl -i -X GET "http://localhost:8080/public/fdas/fda_alarms/das/da_all_alarms/d
   -H "Accept: application/x-ndjson"
 ```
 
-#### Query `POST /plugin/cda/api/doQuery` (Pentaho CDA legacy support)
+#### Query `/plugin/cda/api/doQuery` (Pentaho CDA legacy support)
 
 This endpoint provides backward compatibility with legacy Pentaho CDA clients.
 
@@ -1742,28 +1742,47 @@ executions and transforming the response into CDA-compatible format.
 
 This endpoint does **not** execute queries directly. It delegates execution to the FDA query engine.
 
+Supported methods:
+
+-   `GET /plugin/cda/api/doQuery`
+-   `POST /plugin/cda/api/doQuery`
+
 _**Request headers**_
 
 | Header           | Optional | Description                                                              | Example            |
 | ---------------- | -------- | ------------------------------------------------------------------------ | ------------------ |
-| `Content-Type`   |          | Must be `application/x-www-form-urlencoded`                              | —                  |
+| `Content-Type`   | ✓        | For `POST`, should be `application/x-www-form-urlencoded`                | —                  |
 | `Fiware-Service` | ✓        | Tenant/service name. If not present, it is derived from the `path` field | `trantor`          |
-| `Accept`         | ✓        | Currently ignored (response is always JSON CDA format)                   | `application/json` |
+| `Accept`         | ✓        | Ignored when `outputType` is provided. If omitted, defaults to JSON      | `application/json` |
+
+---
+
+_**Request payload**_
+
+For `POST`, send as `application/x-www-form-urlencoded` body.
+
+For `GET`, send as query parameters.
+
+| Field          | Optional | Description                                                                                                                                                                                                                             | Example                              |
+| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `path`         |          | Path used to resolve context (`visibility`, `service`, and FDA id). Supported formats include `/public/<service>/...` and `home/<service>/verticals/public/<fda>.cda`. If no explicit FDA id is present, it defaults to `dataAccessId`. | `/public/service/verticals/sql/fda1` |
+| `dataAccessId` |          | Identifier of the Data Access (DA) inside the FDA                                                                                                                                                                                       | `da1`                                |
+| `outputType`   | ✓        | Format of the returned results. **Default:** `json`. Allowed values: `json`, `csv`, `xls`.                                                                                                                                              | `csv`                                |
+| `param*`       | ✓        | Query parameters prefixed with `param`. If omitted, no DA query parameters are passed.                                                                                                                                                  | `parammunicipality=NA`               |
+| `pageSize`     | ✓        | Pagination size (must be handled explicitly by the DA). If omitted, this field is not passed and DA defaults apply.                                                                                                                     | `10`                                 |
+| `pageStart`    | ✓        | Pagination offset (must be handled explicitly by the DA). If omitted, this field is not passed and DA defaults apply.                                                                                                                   | `0`                                  |
 
 ---
 
-_**Request body (form-urlencoded)**_
+_**Path-to-scope convention (legacy CDA)**_
 
-The request body must be sent as `application/x-www-form-urlencoded`.
+In this compatibility endpoint, `visibility` and `servicePath` are resolved from `path` to preserve Pentaho legacy
+behavior:
 
-| Field          | Optional | Description                                                                                                           | Example                              |
-| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `path`         |          | Path used to resolve service. FDA identifier defaults to `dataAccessId` if path only has visibility and service.      | `/public/service/verticals/sql/fda1` |
-| `dataAccessId` |          | Identifier of the Data Access (DA) inside the FDA                                                                     | `da1`                                |
-| `outputType`   | ✓        | Format of the returned results. **Default:** `json`. Allowed values: `json`, `csv`, `xls`.                            | `csv`                                |
-| `param*`       | ✓        | Query parameters prefixed with `param`. If omitted, no DA query parameters are passed.                                | `parammunicipality=NA`               |
-| `pageSize`     | ✓        | Pagination size (must be handled explicitly by the DA). If omitted, this field is not passed and DA defaults apply.   | `10`                                 |
-| `pageStart`    | ✓        | Pagination offset (must be handled explicitly by the DA). If omitted, this field is not passed and DA defaults apply. | `0`                                  |
+-   `visibility`: extracted from `path` (`public` or `private`)
+-   `servicePath`: normalized as `/${visibility}`
+
+This convention is intentional and backward compatible with legacy clients that did not manage `Fiware-ServicePath`.
 
 ---
 
@@ -1813,6 +1832,19 @@ curl -i -X POST "http://localhost:8085/plugin/cda/api/doQuery" \
   -d "pageSize=10"
 ```
 
+_**Example Request (GET + query params, JSON default):**_
+
+```bash
+curl -i -X GET "http://localhost:8085/plugin/cda/api/doQuery?path=/public/trantor/verticals/sql/fda1&dataAccessId=da1&paramminAge=25&pageSize=10&pageStart=0"
+```
+
+_**Example Request (GET legacy CKAN/Pentaho style + CSV):**_
+
+```bash
+curl -i -X GET "http://localhost:8085/plugin/cda/api/doQuery?path=home/trantor/verticals/public/environment.cda&dataAccessId=airqualityobserved&paramstart=2023-01-01%2000%3A00%3A00&paramfinish=2023-03-30%2023%3A59%3A59&_TRUST_USER_=opendata_trantor&outputType=csv" \
+    --output results.csv
+```
+
 _**Example Response (JSON):**_
 
 ```json

doc/05_advanced_topics.md

@@ -136,6 +136,7 @@ FDA includes a compatibility layer to support legacy Pentaho CDA clients.
 ### Endpoint
 
 ```
+GET /plugin/cda/api/doQuery
 POST /plugin/cda/api/doQuery
 ```
 
@@ -145,6 +146,7 @@ This layer:
 
 -   Translates CDA-style requests into FDA execution calls
 -   Resolves `service` from `path` if not explicitly provided
+-   Resolves `visibility` and `servicePath` from `path` (with `servicePath = /<visibility>`)
 -   Resolves `fdaId` from the end of `path` field if it includes more than `service` and `visibility`, otherwise
     defaults to `dataAccessId`. It strips the `fdaId` at the end of the path of the `.cda` extension if present
 -   Uses `dataAccessId` as DA identifier
@@ -202,6 +204,8 @@ Currently unsupported features:
 
 These may be implemented in future versions if required.
 
+Detailed reference available at: [`CDA legacy compatibility`](/doc/AdvancedTopics/cda_legacy_compatibility.md)
+
 ---
 
 ## 🧭 Navigation

doc/AdvancedTopics/cda_legacy_compatibility.md

@@ -0,0 +1,63 @@
+# CDA Legacy Compatibility
+
+## Scope
+
+This note documents how FDA keeps backward compatibility with legacy Pentaho CDA clients.
+
+Compatibility endpoint:
+
+-   `GET /plugin/cda/api/doQuery`
+-   `POST /plugin/cda/api/doQuery`
+
+## Why this exists
+
+Legacy CDA clients (for example old BI and CKAN integrations) usually send requests with:
+
+-   no FIWARE headers
+-   transport-level query parameters (`param*`, `pageSize`, `pageStart`)
+-   `path` as the source of tenant/scope context
+
+FDA keeps this behavior intentionally in the compatibility endpoint to avoid forcing migrations in those clients.
+
+## Scope resolution convention
+
+In CDA compatibility mode, context is derived from `path`:
+
+-   `service`: extracted from `path`
+-   `visibility`: extracted from `path` (`public` or `private`)
+-   `servicePath`: normalized as `/${visibility}`
+
+This mirrors historic usage where `Fiware-ServicePath` was not part of the CDA contract.
+
+Supported path styles include:
+
+-   `/public/<service>/verticals/sql/<fdaId>`
+-   `/private/<service>/verticals/sql/<fdaId>`
+-   `home/<service>/verticals/public/<fdaId>.cda`
+-   `home/<service>/verticals/private/<fdaId>.cda`
+
+If `fdaId` cannot be inferred from path, it falls back to `dataAccessId`.
+
+## Request mapping
+
+Input fields are mapped as follows:
+
+-   `dataAccessId` -> DA id
+-   `param*` -> DA params (prefix removed)
+-   `pageSize`, `pageStart` -> forwarded as-is
+-   `outputType` -> response format (`json`, `csv`, `xls`)
+
+Unsupported compatibility feature:
+
+-   `param_not_*`
+
+## Behavior notes
+
+-   For `json`, response is CDA-like: `{ metadata, resultset, queryInfo }`.
+-   For `csv` and `xls`, FDA returns file downloads.
+-   `_TRUST_USER_` can be present in requests and is ignored by FDA.
+
+## Recommended usage
+
+-   Use this endpoint only for legacy clients that require CDA wire format.
+-   Use native FDA endpoints for new integrations.

src/index.js

@@ -636,18 +636,22 @@ app.delete('/datasources/:datasourceId', async (req, res) => {
   return res.sendStatus(204);
 });
 
-app.post('/plugin/cda/api/doQuery', async (req, res) => {
-  const startTime = Date.now();
+function getCdaRequestParams(req) {
+  return req.method === 'GET' ? req.query ?? {} : req.body ?? {};
+}
+
+async function handleCdaDoQuery(req, res) {
+  const requestParams = getCdaRequestParams(req);
+  const { path, dataAccessId } = requestParams;
 
-  const { path, dataAccessId, ...rest } = req.body;
   if (!path || !dataAccessId) {
     return res.status(400).json({
       error: 'BadRequest',
       description: 'Missing params in the request',
     });
   }
 
-  const rawOutputType = req.body.outputType || DEFAULT_OUTPUT_TYPE;
+  const rawOutputType = requestParams.outputType || DEFAULT_OUTPUT_TYPE;
 
   if (!VALID_OUTPUT_TYPES.includes(rawOutputType)) {
     return res.status(400).json({
@@ -658,7 +662,7 @@ app.post('/plugin/cda/api/doQuery', async (req, res) => {
 
   try {
     const result = await handleCdaQuery({
-      body: req.body,
+      body: requestParams,
       outputType: rawOutputType,
     });
 
@@ -672,7 +676,10 @@ app.post('/plugin/cda/api/doQuery', async (req, res) => {
       description: err.message || 'Unexpected error executing query',
     });
   }
-});
+}
+
+app.post('/plugin/cda/api/doQuery', handleCdaDoQuery);
+app.get('/plugin/cda/api/doQuery', handleCdaDoQuery);
 
 // eslint-disable-next-line no-unused-vars
 app.use((err, req, res, next) => {

src/lib/compat/cdaAdapter.js

@@ -24,6 +24,8 @@
 
 import { executeQuery } from '../fda.js';
 
+const VALID_VISIBILITIES = new Set(['public', 'private']);
+
 export async function handleCdaQuery({ body, outputType = 'json' }) {
   const { service, visibility, fdaId, daId, queryParams, servicePath } =
     adaptCdaParams(body);
@@ -52,8 +54,7 @@ function adaptCdaParams(body) {
 
   // --------- RESOLVE SERVICE ----------
   const pathParts = path.split('/').filter(Boolean);
-  const visibility = pathParts[0] || 'private';
-  const service = pathParts.length <= 1 ? pathParts[0] : pathParts[1];
+  const { visibility, service } = resolveServiceContext(pathParts);
   const servicePath = `/${visibility}`;
 
   // fdaId comes at the end of the path (we remove .cda extension if present)
@@ -95,6 +96,34 @@ function adaptCdaParams(body) {
   };
 }
 
+function resolveServiceContext(pathParts) {
+  // Supported styles:
+  // - /public/<service>/...
+  // - home/<service>/verticals/public/<file>.cda
+  if (VALID_VISIBILITIES.has(pathParts[0])) {
+    return {
+      visibility: pathParts[0],
+      service: pathParts.length <= 1 ? pathParts[0] : pathParts[1],
+    };
+  }
+
+  if (pathParts[0] === 'home' && pathParts.length > 1) {
+    const visibilityPart = pathParts.find((part, index) => {
+      return index > 1 && VALID_VISIBILITIES.has(part);
+    });
+
+    return {
+      visibility: visibilityPart || 'public',
+      service: pathParts[1],
+    };
+  }
+
+  return {
+    visibility: pathParts[0] || 'private',
+    service: pathParts.length <= 1 ? pathParts[0] : pathParts[1],
+  };
+}
+
 function adaptToCdaFormat(rows, { pageStart = 0, pageSize = 0 }) {
   if (!rows.length) {
     return {

test/integration/suites/cdaCompatibility.integration.tests.js

@@ -137,6 +137,60 @@ export function registerCdaCompatibilityIntegrationTests({
       expect(ndjsonAttempt.json).toHaveProperty('resultset');
     });
 
+    test('GET /plugin/cda/api/doQuery supports query params without FIWARE headers', async () => {
+      const baseUrl = getBaseUrl();
+      const url = new URL(`${baseUrl}/plugin/cda/api/doQuery`);
+
+      url.searchParams.set('path', `/public/${service}/verticals/sql/${fdaId}`);
+      url.searchParams.set('dataAccessId', daId);
+      url.searchParams.set('paramminAge', '25');
+      url.searchParams.set('pageSize', '2');
+      url.searchParams.set('pageStart', '0');
+
+      const res = await httpReq({
+        method: 'GET',
+        url: url.toString(),
+      });
+
+      expect(res.status).toBe(200);
+      expect(res.json).toHaveProperty('metadata');
+      expect(res.json).toHaveProperty('resultset');
+      expect(res.json).toHaveProperty('queryInfo');
+      expect(res.json.queryInfo.pageStart).toBe(0);
+      expect(res.json.queryInfo.pageSize).toBe(2);
+    });
+
+    test('GET /plugin/cda/api/doQuery supports legacy home path and outputType query param', async () => {
+      const baseUrl = getBaseUrl();
+      const url = new URL(`${baseUrl}/plugin/cda/api/doQuery`);
+
+      url.searchParams.set(
+        'path',
+        `home/${service}/verticals/public/${fdaId}.cda`,
+      );
+      url.searchParams.set('dataAccessId', daId);
+      url.searchParams.set('paramminAge', '25');
+      url.searchParams.set('outputType', 'csv');
+      url.searchParams.set('_TRUST_USER_', `opendata_${service}`);
+
+      const res = await httpReqRaw({
+        method: 'GET',
+        url: url.toString(),
+      });
+
+      expect(res.status).toBe(200);
+      expect(res.headers['content-type']).toContain('text/csv');
+      expect(res.headers['content-disposition']).toContain('results.csv');
+
+      const lines = res.text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+      expect(lines[0]).toBe('id,name,age');
+      expect(lines[1]).toBe('1,ana,30');
+      expect(lines[2]).toBe('3,carlos,40');
+    });
+
     test('POST /plugin/cda/api/doQuery rejects scope mismatch', async () => {
       const baseUrl = getBaseUrl();
       const privateFdaId = 'fda_cda_scope_private';