[openstack-dev] [api] [all] To changes-since or not to changes-since

Sean Dague sean at dague.net
Fri Jun 19 20:25:06 UTC 2015

On 06/19/2015 05:07 AM, Chris Dent wrote:
> 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/

I think that is a reasonable summation. My personal feeling is that if
'changes-since' is strictly defined as the AND of 2 other standard
filters, it's not feeling very relevant to recommend it existing. It's
now just a 2nd way to do exactly the same thing, and all we can do is
screw it up ("A man with one watch always knows what time it is. A man
with two watches is never quite sure.").

If it's left a little more vague of "for resources that you expect to be
regularly polled, this can provide an interface to only show the
consumer relevent resources. If you choose to implement this, you must
document what criteria is used to return resources from the url." And
allow the possibility that their might be different sensible definitions
depending on the resource, I'm happier about it.


Sean Dague

More information about the OpenStack-dev mailing list