There are an incredible amount of times that people are looking to sync with other systems or do other calls that require knowing what changed since some given timestamp.
Currently different endpoints will give you one of the following:
- you include all the properties as properties with history in a RETRIEVE (objects) endpoint, but you still can’t filter the list returned, and you still need to check each change timestamp to see whether first that ID changed, and then if so check each change timestamp within the property history to see which properties changed
- you use a Search endpoint and filter on the record modified property and potentially others, but that doesn’t retrieve history so you end up needing to compare what’s there with what you’ve previously stored, property by property
- with Associations in particular there doesn’t appear to be a history list visible to the API for either additions or archivals. You have to batch fetch it in 100-from:id increments as there’s no “get everything” endpoint, and there’s no way I know of to filter or search associations by modified or time- so you have to get and analyze absolutely everything in order to find the 15 things that changed.
I propose specific endpoints for objects and associations to handle these extremely common queries. Example potential url patterns and abilities:
- all versions example abilities:
- defaults to modified since midnight in whatever timezone the portal is working in (so same cutoff as daily API limit)- this would make it more predictable/stable than something rolling like “last 24 hours” where precise timing of running the call would matter
- only return the properties (and/or records, as applicable) that changed within the given timespan
- a different start time can be passed as a query parameter, in ISO8601 format to make it human-readable instead of any of the epoch mils that have been sometimes used with time, and to make it consistent with some of the existing other uses of time
- would return an empty array of results if nothing modified in the given time
- include additions, updates and deletions
- for lists, the main call would query setup changes, while the memberships call would query membership changes
- single record versions (GET):
- multi-record GET versions:
- multi-record POST versions:
- example endpoint constructions:
- additional options:
- filter for what parameters/association types/etc caller cares about having changed (filter out things that changed but don’t apply to the given situation)
- can specify if want default of added/removed/updated, or some combination of these that’s cared about (such as only those removed for auditing purposes)
- give a list of ID’s to query changes from