Aggregate Functions

Overview

The Aggregate Functions API allows you to perform statistical calculations (average, sum, minimum, maximum, count, list) on numeric fields in list responses. This enables data analysis and trend identification without making additional API calls.

Endpoint

POST /ws/rest/{Resource}/aggregate

Request Parameters

Query Parameters

Our standard filtering functionality can be used to filter data before applying aggregate functions.

Request Body

The request body must contain a JSON object with a functions array that specifies which aggregate functions to perform on which fields.

{
  "functions": [
    {
      "type": "string",  // Aggregate function type
      "field": "string"  // Field to aggregate
    }
  ]
}

Supported Aggregate Function Types

Type	Description	Applicable Fields
avg	Calculates the average value	Numeric fields only
sum	Calculates the sum of all values	Numeric fields only
min	Finds the minimum value	Numeric fields only
max	Finds the maximum value	Numeric fields only
count	Counts the number of non-null values	Any field
list	Returns a list of all unique values	Any field

Special Field Values

• For count function, you can use * as the field value to count all records.

Response

The API returns a JSON object with a results array containing the computed aggregate values.

{
  "results": [
    {
      "type": "string",    // The aggregate function type
      "field": "string",   // The field that was aggregated
      "value": any         // The result of the aggregate function
    }
  ]
}

The value field will contain:

• A numeric value for avg, sum, min, max, and count functions

• An array of values for the list function

Examples

Calculate Average of a Numeric Field

Request:

POST /ws/rest/VoyageHeader/aggregate

Request Body:

{
  "functions": [
    {
      "type": "avg",
      "field": "doRobVoyageStart"
    }
  ]
}

Response:

{
  "results": [
    {
      "type": "avg",
      "field": "doRobVoyageStart",
      "value": 125.4
    }
  ]
}

Calculate Multiple Aggregates with Filter

Request:

POST /ws/rest/VoyageHeader/aggregate?filter=voyage.isTc(EQ)true

Request Body:

{
  "functions": [
    {
      "type": "sum",
      "field": "foRobVoyageStart"
    },
    {
      "type": "min",
      "field": "foPriceVoyageStart"
    },
    {
      "type": "list",
      "field": "referenceNo"
    }
  ]
}

Response:

{
  "results": [
    {
      "type": "sum",
      "field": "foRobVoyageStart",
      "value": 1250.6
    },
    {
      "type": "min",
      "field": "foPriceVoyageStart",
      "value": 450.75
    },
    {
      "type": "list",
      "field": "referenceNo",
      "value": ["V2023-001", "V2023-002", "V2023-003"]
    }
  ]
}

Count All Records

Request:

POST /ws/rest/VoyageHeader/aggregate

Request Body:

{
  "functions": [
    {
      "type": "count",
      "field": "*"
    }
  ]
}

Response:

{
  "results": [
    {
      "type": "count",
      "field": "*",
      "value": 123
    }
  ]
}

Error Handling

The API validates the request and returns appropriate error messages:

• If an invalid function type is specified, the API returns HTTP 400.

• If an invalid field is specified, the API returns HTTP 400.

• If an incompatible function type is used with a field (e.g., "avg" on a text field), the API returns HTTP 400.

Error Response Example

{
  "statusCode": 400,
  "message": "Cannot apply 'avg' function to field 'testText'. Only numeric fields are supported for this operation."
}

Limitations

• Date aggregation functions (min/max) are not supported and will return a 400 error.

• Text fields cannot be used with numeric aggregate functions (avg, sum, min, max) and will return a 400 error.

• All fields must exist in the data model, or the request will be rejected.