It could use a section on high level justification / inspiration.<p>For example, what inspired this over a typical paginated API that lets you sort old to new with an afterId parameter?
Because the client requests pagination by lastEventId (a UUID), the server needs to remember every event forever in order to correctly catch up clients.<p>If instead the client paginated by lastEventTimestamp, then a server that for any reason no longer had a particular event UUID could at least start at the following one.
I think that HTTP is not the best way to do it, and that JSON is also not the best way to do it. (HTTP may work reasonably when you only want to download existing events and do not intend to continue polling.)<p>I also think using UUID alone isn't the best way to make the ID number. If events only come from one source, then just using autoincrementing will work (like NNTP does for article numbers within a group); being able to request by time might also work (which is also something that NNTP does).
What happens if you need to catch up? You keep calling in a loop with a new lastEventId?<p>What is the intention there though. Is this for social media type feeds, or is this meant for synchronising data (at the extreme for DB replication for example!).<p>What if anything is expected of the producer in terms of how long to store events?
This is an astonishingly bad idea. Don't do this.<p>Use HTTP server-sent events instead. Those can keep the connection open so you don't have to poll to get real-time updates and they will also let you resume from the last entry you saw previously.<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events" rel="nofollow">https://developer.mozilla.org/en-US/docs/Web/API/Server-sent...</a>