Guides

Working with List Endpoints

Manipulating responses that contain lists of resources

Suggest Edits

This guide explains how to effectively use list endpoints in Transact API. All list endpoints in this API follow a consistent pattern, allowing for efficient querying, filtering, and sorting of data.

Basic Structure

A typical request to a list endpoint looks like this:

GET /v3/{resource}

Where {resource} is the name of the resource you're querying (e.g., ppex/orders, parties, accounts, links, trades etc.).

Query Parameters

List endpoints support the following query parameters:

  1. limit: Number of records to return
  2. offset: Number of records to skip before starting to return results
  3. filter: Conditions to filter the results
  4. sort: Field(s) and direction to sort the results

Pagination

Use limit and offset for pagination:

GET /v3/{resource}?limit=10&offset=20

This returns 10 records, starting from the 21st record.

Sorting

Use the sort parameter to specify the field and direction for sorting:

GET /v3/{resource}?sort=fieldName:asc

Use :asc for ascending order and :desc for descending order.

Filtering

The filter parameter allows you to specify conditions for the returned data. You can use simple filters, array filters, and range filters.

  1. Simple filter (exact match):

    GET /v3/{resource}?filter[fieldName]=value

  2. Array filter (IN clause):

    GET /v3/{resource}?filter[fieldName][]=value1&filter[fieldName][]=value2

  3. Range filter:

    GET /v3/{resource}?filter[fieldName][min]=minValue&filter[fieldName][max]=maxValue

    For range filters, you can specify inclusivity:

    GET /v3/{resource}?filter[fieldName][min]=minValue&filter[fieldName][max]=maxValue&filter[fieldName][min_inclusive]=false&filter[fieldName][max_inclusive]=false

    By default, ranges are inclusive. Use min_inclusive=false or max_inclusive=false to make them exclusive. This works well for date ranges where you want to get all records that were created on a particular day.

    GET /v3/ppex/orders?filter[updatedDate][min]=1999-01-22&filter[updatedDate][max]=1999-01-23&filter[updatedDate][max_inclusive]=false

    This will retrieve only records that were updated on January 22, 1999. You can also get records from a particular hour of the day:

    GET /v3/ppex/orders?filter[updatedDate][min]=1999-01-22T10:00:00-0500&filter[updatedDate][max]=1999-01-22T11:00:00-0500&filter[updatedDate][max_inclusive]=false

    This will retrieve only records that occurred during the 10 'o'clock hour Eastern Standard Time.

  4. Multiple filters:

    GET /v3/{resource}?filter[field1]=value1&filter[field2][min]=minValue&filter[field2][max]=maxValue

    Multiple filters are combined with AND logic.

  5. Filters can also be defined using JSON syntax:

    GET /v3/{resource}?filter={"fieldName": "value"}
GET /v3/{resource}?filter={"field1": "value1", "field2":{"min":minValue, "max": maxValue, "maxInclusive": false}

Advanced Filtering

Transact API supports advanced filtering options, allowing for more complex and precise data queries. You can use various operators to filter your results based on different conditions.

Filter Operators

The following operators are now available for filtering:

  1. eq: Equal to
  2. ne: Not equal to
  3. gt: Greater than
  4. gte: Greater than or equal to
  5. lt: Less than
  6. lte: Less than or equal to
  7. in: In a list of values
  8. nin: Not in a list of values
  9. like: Pattern matching (using SQL LIKE syntax)
  10. between: Between two values (inclusive)

Using Advanced Filters

To use these advanced filters, you can specify them in the filter parameter using JSON syntax. Here are some examples:

  1. Equal to:

    GET /v3/{resource}?filter={"fieldName": {"eq": "value"}}

  2. Not equal to:

    GET /v3/{resource}?filter={"fieldName": {"ne": "value"}}

  3. Greater than:

    GET /v3/{resource}?filter={"fieldName": {"gt": 100}}

  4. Less than or equal to:

    GET /v3/{resource}?filter={"fieldName": {"lte": "2023-06-01"}}

  5. In a list of values:

    GET /v3/{resource}?filter={"fieldName": {"in": ["value1", "value2", "value3"]}}

  6. Pattern matching:

    GET /v3/{resource}?filter={"fieldName": {"like": "%pattern%"}}

  7. Between two values:

    GET /v3/{resource}?filter={"fieldName": {"between": ["2023-01-01", "2023-12-31"]}}

Combining Multiple Filters

You can combine multiple filters in a single query. The filters will be applied with AND logic:

GET /v3/{resource}?filter={"field1": {"gt": 100}, "field2": {"in": ["A", "B"]}, "field3": {"like": "%test%"}}

This query will return results where field1 is greater than 100 AND field2 is either "A" or "B" AND field3 contains the word "test".

Range Filters

The existing range filter syntax is still supported and works as before:

GET /v3/{resource}?filter={"fieldName": {"min": minValue, "max": maxValue, "min_inclusive": true, "max_inclusive": false}}

Data Type Handling

The API automatically handles data type conversion for date/time and numeric values:

  • Date/time values are converted to the format "YYYY-MM-DD HH:MM:SS"
  • Numeric values are converted to floating-point numbers

Error Handling

If an invalid filter is provided, the API will return a 422 error with the description "invalid filter". Always ensure that your filter syntax is correct and that you're using valid field names and operators.

Response Format

List endpoints typically return responses in this format:

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "data": [
    {
      // Resource-specific fields
    },
    // More items...
  ],
  "pagination": {
    "totalRecords": number,
    "startIndex": number,
    "endIndex": number
  }
}

Tips and Best Practices

  1. Start with a small limit to test your query before requesting larger datasets.
  2. Use filters to reduce the amount of data transferred and processed.
  3. When using date or numeric ranges, the API automatically converts values to the appropriate format.
  4. Combine filters and sorting to get precisely the data you need.
  5. Pay attention to the pagination object in the response to handle large datasets effectively.

Error Handling

If your request is invalid or an error occurs, the API will return an appropriate error code and description. Always check the statusCode and statusDesc in the response. The API implements robust error handling to provide clear feedback on request issues. Here are common error scenarios:

  1. Invalid Pagination Parameters:

    • If offset or limit is not a valid integer, you'll receive a 422 error with code "1422" and a description explaining the issue.
    • If limit is out of the allowed range (1 to 500), you'll get a 422 error with code "239" and a description of the valid range.
    • If offset is negative or exceeds the total number of records, you'll receive a 422 error with code "239" and a description of the valid range. Note that for empty result sets, even an offset of 0 will trigger this error, as it technically exceeds the total number of records (which is 0).

  2. Invalid Filter:

    • If the filter parameter cannot be decoded (for JSON-encoded filters), you'll get a 400 error.
    • If the filter contains invalid fields or values, you'll receive a 422 error with a description "invalid filter".

  3. Authorization Issues:

    • If the required scopes are not granted, you'll get a 403 error with the description "permission denied".

  4. General Errors:

    • Other errors will return appropriate HTTP status codes (e.g., 400 for bad requests, 500 for server errors) with a descriptive message.

Error responses follow this general structure:

{
  "statusCode": "ERROR_CODE",
  "statusDesc": "Error description",
  "data": []
}

This guide provides a general overview of working with list endpoints in Transact API. For specific details about individual endpoints, please refer to the dedicated documentation for each resource.

Updated 7 days ago