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

Devdatta Kulkarni devdatta.kulkarni at RACKSPACE.COM
Fri Jun 19 20:23:44 UTC 2015

From: Chris Dent <chdent at redhat.com>
Sent: Friday, June 19, 2015 4:07 AM
To: OpenStack-dev at lists.openstack.org
Subject: [openstack-dev] [api] [all] To changes-since or not to changes-since

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:


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

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 am wondering what are the reasons that "changes-since" seems
to introduce magic, ambiguity and inconsistency into the API?
Could this be addressed by requiring each service to precisely define
what resources would be returned in response to the "changes-since" query?
If each service defines this contract then there should not be any
ambiguity on what resources to expect in the response of the query.

That said, we may need to precisely define semantics of what it means
to correctly implement this feature. For instance, could we define
that the set of resources once returned by a particular timestamp
in the query would be guaranteed to remain same for subsequent
executions of the query (idempotency argument)? This may be difficult
to ensure in systems that may be built around providing eventual guarantees.

- Devdatta

More information about the OpenStack-dev mailing list