Platform API overview

This reference describes the requests and responses used to configure the exchange and retrieve its data.

General considerations

The following applies to the examples provided in this reference:

  • All endpoints are relative and resolved based on a specified hostname (indicated here as [host]).

    Both the hostname and your admin credentials are configured when setting up the exchange.

  • Only private methods are used to access data.

    All requests except for Authorization must include an appropriate HTTP header: Authorization: Bearer <Access Token>.

  • The required fields are marked as required.

Shaping report data

Described below are the filtering options, as well as the sorting and pagination parameters that can be specified when retrieving the exchange data.

Note

When using methods to create custom web pages, you may need to send separate requests and retrieve data for different page sections at a time, such as a page header presenting summary information and a data table displaying the details.

To learn more, refer to Reporting methods for Admin Panel pages.

Filtering

Depending on your requirements, various filters may be applied to the report data that is being retrieved.

In such cases, the following parameters are included in the filters section:

  • field — the name of a field used to filter the response data.

    Specific fields may be required for some requests (such as userId indicating the users for which the details are requested).

    The fields by which the response data can be filtered are listed for each request.

  • entryType — the data format in which the values of filter parameters are specified:

    • Exact for string values:

    • FloatDateRange for date-time ranges relative to the current date and time

    • DateRange for time-range values that don’t reference the current date and time

    • NumericRange for numeric ranges

    • SearchTerm for partial matches

    The Exact entry type is used for string parameters. With this type, you can specify the following options, which indicate the values that will be retrieved:

    • values — an array of string values indicating the data records to include in the response.

    • excludefalse by default. If true, data records meeting the specified filter criteria must be excluded from a response.

    With FloatDateRange, you can specify the following fields to define the time range:

    • offset — an integer value indicating the time interval, as a number of time units (defined by offsetUnit) to count back from the current time.

    • offsetUnit — a string value, specifying the time unit to count back time (Days, Weeks, Months or Years).

    For filters defining a value range (such as various amounts and time periods defined as DateRange and NumericRange), the from and to fields indicate a value range (such as AmountInRootAsset) or a time period (such as createdAt). If either of these two fields is unspecified, the value range is limited only by its higher or lower bound. If both these fields are unspecified, the filter is not applied.

    The SearchTerm entry type is used to retrieve the records that fully or partially match the specified string.

Sorting

To sort the report data that is being retrieved, the request must include the following parameters, specifying the name of the sorting field and the sorting order:

  • field — the name of a field used to sort page data.

  • direction — the order in which the data is sorted: Desc or Asc.

In the following example, the data is sorted by the Asset field in the descending order:

"sort": {
  "field": "Asset",
  "direction": "Desc"
}

The data can be sorted only by a single field at a time.

Pagination

When creating reports, you can use the following options to retrieve data in pages:

  • page — the current page number.

  • perPage — the number of records to show on each page.

For example, to skip the first 40 records and retrieve the next 20 records, set the page field to 3, and perPage to 20.