Query Parameters

Query params

When triggering a data exchange, it is possible to add specific query parameters that will be used in the exchange:

Currently, the query parameters are only used when exporting data from the provider.

Query parameters can be applied in any case of the consumer/exchange routes: using the type, providerEndpoint, or only the contract fields.

Applying Query Parameters to All Provider Resources

{
    "purposeId": "https://a-ptx-catalog.com/v1/catalog/serviceofferings/66d18b79ee71f9f096baecb0",
    "resourceId": "https://a-ptx-catalog.com/v1/catalog/serviceofferings/66d187f4ee71f9f096bae8ca",
    "contract": "https://a-ptx-contract-service.com/contracts/66db1a6dc29e3ba863a85e0f",
    "providerParams": {
        "query": [
            {
                "page": 2
            },
            {
                "limit": 20
            }
        ]
    }
}

By adding the providerParams field at the exchange, the query will be applied to all data resources of the provider during data export. The required format for the providerParams field is:

 {
  "query": [
    {
      "anyString": "anyValue"
    },
    {
      "anyString": "anyValue"
    }
    // add more...
  ]
}

Applying Query Parameters to a Specific Resource

If you want to apply query parameters to only one resource, you can specify them in the resources field:

{
    "purposeId": "https://a-ptx-catalog.com/v1/catalog/serviceofferings/66d18b79ee71f9f096baecb0",
    "resourceId": "https://a-ptx-catalog.com/v1/catalog/serviceofferings/66d187f4ee71f9f096bae8ca",
    "contract": "https://a-ptx-contract-service.com/contracts/66db1a6dc29e3ba863a85e0f",
    "resources": [
      {
        "resource": "https://a-ptx-catalog.com/v1/catalog/dataresources/66d1889cee71f9f096bae98b",
        "params": {
          "query": [
            {
              "page": 2
            },
            {
              "limit": 20
            }
          ]
        }
      }
    ]
}

In this case, the query parameters page and limit will be applied to the data resource 66d1889cee71f9f096bae98b.

Requirements

To allow the connector to apply query parameters, the resource representation must contain a queryParams field with the corresponding queries.

Example of a data resource:

 {
  "@context": "https://a-ptx-catalog.com/v1/dataresource",
  "@type": "DataResource",
  "_id": "66d1889cee71f9f096bae98b",
  "aggregationOf": [],
  "name": "Provider",
  "description": "provider",
  "copyrightOwnedBy": [],
  "license": [],
  "policy": [],
  "producedBy": "66d18724ee71f9f096bae810",
  "exposedThrough": [],
  "obsoleteDateTime": "",
  "expirationDateTime": "",
  "containsPII": false,
  "anonymized_extract": "",
  "archived": false,
  "attributes": [],
  "category": "6090ff950d9b6451c24ac0b0",
  "isPayloadForAPI": false,
  "country_or_region": "WORLD",
  "entries": 0,
  "subCategories": [],
  "schema_version": "1",
  "b2cDescription": [],
  "createdAt": "2024-08-30T08:53:48.891Z",
  "updatedAt": "2024-08-30T08:53:48.940Z",
  "__v": 0,
  "representation": {
    "_id": "66d1889cee71f9f096bae996",
    "resourceID": "66d1889cee71f9f096bae98b",
    "fileType": "",
    "type": "REST",
    "url": "https://provider.api.com/api/users",
    "sqlQuery": "",
    "className": "",
    "method": "none",
    "credential": null,
    "createdAt": "2024-08-30T08:53:48.945Z",
    "updatedAt": "2024-08-30T08:53:48.945Z",
    "__v": 0,
    "queryParams": [ "page", "limit", "skip" ] // required
  }
}

In this example only the query parameters page, limit, and skip will be interpreted by the connector.

Concrete example

I'm a Provider and my data resource is as follows:

 {
  "@context": "https://a-ptx-catalog.com/v1/dataresource",
  "@type": "DataResource",
  "_id": "66d1889cee71f9f096bae98b",
  "aggregationOf": [],
  "name": "Provider",
  "description": "provider",
  "copyrightOwnedBy": [],
  "license": [],
  "policy": [],
  "producedBy": "66d18724ee71f9f096bae810",
  "exposedThrough": [],
  "obsoleteDateTime": "",
  "expirationDateTime": "",
  "containsPII": false,
  "anonymized_extract": "",
  "archived": false,
  "attributes": [],
  "category": "6090ff950d9b6451c24ac0b0",
  "isPayloadForAPI": false,
  "country_or_region": "WORLD",
  "entries": 0,
  "subCategories": [],
  "schema_version": "1",
  "b2cDescription": [],
  "createdAt": "2024-08-30T08:53:48.891Z",
  "updatedAt": "2024-08-30T08:53:48.940Z",
  "__v": 0,
  "representation": {
    "_id": "66d1889cee71f9f096bae996",
    "resourceID": "66d1889cee71f9f096bae98b",
    "fileType": "",
    "type": "REST",
    "url": "https://provider.api.com/api/users",
    "sqlQuery": "",
    "className": "",
    "method": "none",
    "credential": null,
    "createdAt": "2024-08-30T08:53:48.945Z",
    "updatedAt": "2024-08-30T08:53:48.945Z",
    "__v": 0,
    "queryParams": [ "page", "limit", "skip" ]
  }
}

When triggering the exchange, I will use the /consumer/exchange route on my connector with the following body:

{
    "purposeId": "https://a-ptx-catalog.com/v1/catalog/serviceofferings/66d18b79ee71f9f096baecb0",
    "resourceId": "https://a-ptx-catalog.com/v1/catalog/serviceofferings/66d187f4ee71f9f096bae8ca",
    "contract": "https://a-ptx-contract-service.com/contracts/66db1a6dc29e3ba863a85e0f",
    "resources": [
      {
        "resource": "https://a-ptx-catalog.com/v1/catalog/dataresources/66d1889cee71f9f096bae98b",
        "params": {
          "query": [
            {
              "page": 2
            },
            {
              "limit": 20
            },
            {
              "skip": 10
            }
          ]
        }
      }
    ]
}

To retrieve the data, my connector will make an HTTP request to this endpoint:

https://provider.api.com/api/users?page=2&limit=20&skip=10