Update contract schema

[dburriss]

I am updating the schema of responses. I wanted to highlight the changes and get some feedback.

HAL like naming

• https://en.wikipedia.org/wiki/Hypertext_Application_Language
• https://stateless.group/hal_specification.html
• https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-08

Impact:

• except for reserved words like _link, underscores have been removed
• instead of a URL string for each action a { href = "" } object is used. This is inline with HAL and allows for other features in the future.
• kept terms like tail over last as we are really tailing the last page, since it will change as event come in.

Optional features of HAL like CURIE (compact URI), templated, type, are not currently used.

Errors

• I propose we move from 400 to 404 for a page that does not exist
• I propose we use ProblemDetails to return more helpful messages

_linlk actions

• meta (optional - will not appear on meta)
• self
• head
• tail
• previous (optional - will not appear on first page or meta)
• next (optional - will not appear on last page or meta)
• page (templated)

Additional endpoints

I propose that an endpoint along the default route api/event-feed/page/{pageNumber} is valid.

• api/event-feed: meta data
• api/event-feed/page: redirect to first page
• api/event-feed/page/{valid page}: return page with 200

The above is very much geared toward "what would an event processing consumer need". An alternative is a more RESTful API.

• api/event-feed/pages: list pages (probably needs to be paged itself which could get weird from a naming point of view)
• api/event-feed/pages/{valid page}: return page with 200

An open question is whether we want some aliases, then main one for me would be: api/event-feed/page/tail (or last :P ) It gives an easy way to get the last without getting another page first.

[dburriss]

@Grepsy some design questions. What do you think?

[Grepsy]

All the link actions and naming make sense to me, no proposed changes. I like the more RESTful proposal better/feels more natural. The api/event-feed/page/tail also makes sense.

I'm not sure the /pages would require paging, it feels a bit awkward to me, I'm wondering if we can come up with some sort of threshold in response size where this would be necessary. Now that I'm thinking about it, does it make sense to list all pages in a list, or can we get away with just a single metadata-block describing the pages?

Edit: Ah wait, upon reading this again, I realize why you want the /pages to list all pages, to make it more RESTful. In that case I like the first proposal better :-)

[dburriss]

Closed by PR #9