Vote on options in increasing ExtraData and Pagination in a Reference Data system

[Josh Zamor]

This morning on the technical committee call one of our goals was to recommend an approach for Reference Data's recent major releases - specifically focused on options for addressing Pagination needs and ExtraData functionality.  It's the section titled "In a Reference Data system the major semantic version always goes up...  now you know what's up" (yeah like the song Entropy).

We covered the pros/cons we saw for the 3 options outlined, and we thought we'd give voting a try.

To vote on your recommendation between the three options, please cast your vote in this poll:

http://doodle.com/poll/6rrqzmb6thyiwtai

The deadline for your vote is Thursday Apr 20th 2017 at 11:59pm UTC.  All votes welcome, though anonymity is not - so please use the name you're known by to this group.

To the polls!

[Paweł Nawrocki]

Did we consider making pagination optional (at least temporarily to avoid increasing major version all the time)?

Let's say we call:

/api/geographicZones

And we get a response like this:

[ { zone }, { zone }, ... ]

But, when we call:

/api/geographicZones?page=2 (or whatever pagination parameter)

Only then we get a response wrapped in pagination object.

Guess that might require some more effort on backend, but I guess we'd avoid backwards compatibility issues.

Best,

Paweł

[Josh Zamor]

Have to attend the call to suggest new options Pawel!

In reality though I think we can consider such an approach similar enough to option 2, that for voting purposes we can group them as one and the same.

I have some further comments about your particular suggestion:

1. Adding a query parameter that changes the schema returned doesn't feel very RESTful, and it wouldn't work very well with our RAML tester.
2. We also identified adding ExtraData to a Resource.  Doing so would push the Resource's Search endpoint from GET to POST, which would break the contract and result in a new Reference Data major version regardless.

Otherwise I appreciate the craftiness.

Best,

Josh