Formating

Filtering

JSON’s general filtering syntax can be used across all ethos APIs. Support for specific operators and fields is specific to each endpoint. Please refer to the filter query parameter guide in the API reference documentation for specific operator and field support per endpoint.

The filtering syntax for ethos APIs uses the standardized ?filter query parameter for all endpoints that support filter operations.

Sorting

Where supported, sorting is handled using the ?sort query parameter followed by a field name. Reverse sorting is specified using a - prefix.

Example GET /api/location/countries/?sort=az sorts events by alphabetical sequence ascending; GET /api/location/countries/?sort=-az sorts by alphabetical descending.

For more examples, view our JSON sorting guide.

Sparse fieldsets

ethos API endpoints support sparse fieldsets to allow developers to select only requested fields of resources, rather than having to retrieve entire resources (which may be very large).

Sparse fieldsets are specified using the ?fields[TYPE]=field1,field2 query parameter, where TYPE is the resource type from which to select only field1 and field2. This also works for included resource types, e.g. ?fields[INCLUDED-TYPE]=field1,field2; however you also need to include that resource in your request, using the include query parameter for this to work.

To learn more about sparse fieldsets, see our JSON sparse fieldsets guide.

Pagination

Our APIs support cursor-based pagination with the query parameter ?page[cursor].

Paginated resource responses will contain a specific set of pagination cursor helper links in their top-level links object, like the following:

// Basic JSON example
{
  "data": [
    ...
  ],
  "links" : {
    "next" : "https://api.heyethos.com/api/customers/?page=1",
    "prev" : null,
    "self" : "https://api.heyethos.com/api/customers"
  }
}

Datetimes

All datetimes across all ethos APIs in URLs, request, and response bodies must be formatted as ISO 8601 RFC 3339 datetime strings.

Example: 2024-07-23T23:20:50.52Z

Conclusion

The Changelog section is your starting point for exploring the application. Follow the steps above to get started quickly and easily.