HIP-980: Extend mirror node APIs with timestamp query

[IvanKavaldzhiev]

Opening up discussion for:
#980

[Neurone]

Hi @IvanKavaldzhiev, I've seen we improved the timestamp description, but I think this issue still needs to be addressed.

The timestamp query parameter will support having a range of timestamps. For example, timestamp=gt:X&timestamp=lt:Y will return a single result with the entity or entity-related info in the most recent state within the range that is greater than X and less than Y, where X and Y are different timestamps.

My understanding is that there's no point in using a time range because it's essentially ignored and works as a single lt:Y query.

Suppose we decided to always return a single state and, thus, not support time range. In that case, we should use a different parameter type for the timestamp, and I strongly suggest using a different parameter name also (fixed.timestamp, timestamp.fixed, timestamp.single, etc.).

The goal is to be as clear as possible and avoid misunderstandings in API usage. I don't see advantages in recycling an existing parameter type/name if it behaves differently in other cases.

[IvanKavaldzhiev]

The main idea of the enhanced description is to align the timestamp query param behaviour with the same logic as other APIs related to entities - e.g. /api/v1/contracts/{id}?timestamp= . We should be consistent with the behaviour of all entity related APIs.

If we want to change the name of the param and differentiate it with the timestamp range utilized in /blocks API for example (where we return all applicable blocks) - I think this should be included in a separate HIP, while HIP-980 aims to enhance existing APIs and not change the behaviour of the query param.

[Neurone]

I agree; I'm not proposing to change a behavior, but the opposite. To remain consistent and coherent, we should not use a parameter that does not function properly; we should use a new one. This is the moment to do it because we are introducing a new parameter to multiple endpoints.

If this is a flaw we have also in other endpoints (i.e. the one you mentioned) it's important we avoid perpetrating and spreading that by reusing the wrong parameter type in new updates.

Also, I agree we can use another HIP to modify the past, but this is a lower priority than not continuing with the error.

[steven-sheehy]

timestamp is the appropriate name and consistent with other entity APIs. If we change the APIs in this HIP to be something other than timestamp that we're only making it inconsistent with accounts/{id} and contracts/{id}. Timestamps apply differently to entities vs transaction data. The primary key of transaction data is the timestamp so you can show multiple rows because you're expanding that user given range.

The primary key for entities is the entity ID, NFT ID, etc. We can't show multiple rows for a distinct ID as that violates the existing API and its pagination. So any timestamp could only show one row per ID regardless of when that entity was updated. However, it is still a range search and can take in multiple parameters. If you had an entity updated at T2, T4, T6 and you search for timestamp=gte:1&timestamp=lt:5 it would show the most recent update to that entity in that range and return T4. Users don't always know the exact time they updated their entity and want to find it within some estimated range of time.

[Neurone]

Ok, thanks for the clarifications. Let's proceed this way.