Open Stack

There's an open question in the API-WG on whether to formalize or
otherwise enshrine the concept of a "changes-since" query parameter
on collection oriented resources across the projects. The original
source of this concept is from Nova's API:

     http://docs.openstack.org/developer/nova/v2/polling_changes-since_parameter.html

There are arguments for and against but we've been unable to reach a
consensus so the agreed next step was to bring the issue to the
mailing list so more people can hash it out and provide their input.
The hope is that concerns or constraints that those in the group
are not aware of will be revealed and a better decision will be
reached.

The basic idea of "changes-since" is that it can be used as a way to
signal that the requestor is doing some polling and would like to
ask "Give me stuff that has changed since the last time I checked".
As I understand it, for the current implementations (in Nova and
Glance) this means "including stuff that has been deleted". Repeated
requests to the resource with a "changes-since" parameter gives a
running report on the evolving state of the resource. This is intended
to allow "efficient polling"[0].

The pro camp on this likes it because this is very useful and quite
humane: The requestor doesn't need to know the details of how the
query is is implemented under the hood. That is, if there are
several timestamps associated with the singular resources in the
collection which of those are used for time comparison and which
attributes (such as "state" with a value of "deleted") are used to
determine if a singular resource is included. The service gets to
decide these things and in order for "efficient polling" to actually
be achieved it needs to do in order to make effective queries of the
data store.

The con camp doesn't like it because it introduces magic, ambiguity
and inconsistency into the API (when viewed from a cross-project
perspective) and one of the defining goals of the working group is
to slowly guide things to some measure of consistency. The
alternate approach is to formulate a fairly rigorous query system
for both filtering[1] and sorting[2] and use that to specify
explicit queries that state "I want resources that are newer than time
X in timestamp attribute 'updated_at' _and_ have attribute 'state'
that is one of 'foo', 'bar' or 'baz'".

(I hope I have represented the two camps properly here and not
introduced any bias. Myself I'm completely on the fence. If you
think I've misrepresented the state of things please post a
clarifying response.)

The questions come down to:

* Are there additional relevant pros and cons for the two proposals?
* Are there additional proposals which can address the shortcomings
   in either?

Thanks for your input.

[0] Please try to refrain from responses on the line of "ha!
     efficiency! that's hilarious!" and "ZOMG, polling, that's so
     last century". Everybody knows this already and it's not
     germane to the immediate concerns. We'll get to a fully message
     driven architecture next week. This week we're still working
     with what we've got.
[1] filtering guideline proposal
     https://review.openstack.org/#/c/177468/
[2] sorting guideline proposal
     https://review.openstack.org/#/c/145579/
-- 
Chris Dent tw:@anticdent freenode:cdent
https://tank.peermore.com/tanks/cdent