Hi Vaughn,
The Platform REST API is engineered to support a distributed model, where the modules within the Platform, integrated systems (other platforms with their own functional domain connected to Platform), and "extensions" (functionality built on top of Platform) are combined to deliver the mix of processes and functions required.
To support this the assumption is that each integration will primarily use the changes?since function to take change events from the API and then act on them.
Where possible the preferred approach would be to use a CRUD style pattern.
Change events are received from change?since and the integration does the filtering to decide if it's interested in the change i.e. the business logic implemented by the integration is fully encapsulated within it with a clear separation of concerns. (We are working on adding filters so that only events for resources matching the filter are communicated - no timeline at this point).
This does rely on there being suitable aggregation as part of the endpoints, which in itself is a balancing act in terms of filterability and performance -- returning unwanted aggregated data -- with no right answer for all users.
We've tended towards keeping the level of aggregation low.
If a more complex understanding is required connecting across endpoint then it's assumed the integration will take the change events and build it's own read model, and then act on that. i.e. the CQRS pattern.
In this example, the integration would take a feed from the AccountCustomers, Invoices, CreditNotes, and Payments endpoints, and build a read model with the customer balance. Then act on that.
Alternatly the properties that express a relationship between resources (those with a name starting Related...) all have filters on them so the API can be crawled and an aggregate created by the integration.