Replace the 'NOTE' and 'TODO' words with the note and todo directives in the Compute API guide. Improve some format in the guide. e.g. Fix unnecessary bold characters. Change-Id: I7e9d6b8a5228886fd5de03d12482481d2b652666 Closes-Bug: #1558459
4.0 KiB
Efficient polling
The REST API allows you to poll for the status of certain operations
by performing a GET on various elements. Rather than
re-downloading and re-parsing the full status at each polling interval,
your REST client may use the changes-since
and/or
changes-before
parameters to check for changes within a
specified time.
The changes-since
time or changes-before
time is specified as an ISO 8601 dateTime
(2011-01-24T17:08Z). The form for the
timestamp is CCYY-MM-DDThh:mm:ss. An optional time zone
may be written in by appending the form ±hh:mm which describes the
timezone as an offset from UTC. When the timezone is not specified
(2011-01-24T17:08), the UTC timezone is
assumed.
The following situations need to be considered:
If nothing has changed since the
changes-since
time, an empty list is returned. If data has changed, only the items changed since the specified time are returned in the response. For example, performing a GET against:https://api.servers.openstack.org/v2.1/servers?changes-since=2015-01-24T17:08Z
would list all servers that have changed since Mon, 24 Jan 2015 17:08:00 UTC.
If nothing has changed earlier than or equal to the
changes-before
time, an empty list is returned. If data has changed, only the items changed earlier than or equal to the specified time are returned in the response. For example, performing a GET against:https://api.servers.openstack.org/v2.1/servers?changes-before=2015-01-24T17:08Z
would list all servers that have changed earlier than or equal to Mon, 24 Jan 2015 17:08:00 UTC.
If nothing has changed later than or equal to
changes-since
, or earlier than or equal tochanges-before
, an empty list is returned. If data has changed, only the items changed betweenchanges-since
time andchanges-before
time are returned in the response. For example, performing a GET against:https://api.servers.openstack.org/v2.1/servers?changes-since=2015-01-24T17:08Z&changes-before=2015-01-25T17:08Z
would list all servers that have changed later than or equal to Mon, 24 Jan 2015 17:08:00 UTC, and earlier than or equal to Mon, 25 Jan 2015 17:08:00 UTC.
Microversion change history for servers, instance actions and
migrations regarding changes-since
and
changes-before
:
- The 2.21 microversion allows reading instance actions for a deleted server resource.
- The 2.58
microversion allows filtering on
changes-since
when listing instance actions for a server. - The 2.59
microversion allows filtering on
changes-since
when listing migration records. - The 2.66
microversion adds the
changes-before
filter when listing servers, instance actions and migrations.
The changes-since
filter nor the
changes-before
filter change any read-deleted behavior in
the os-instance-actions or os-migrations APIs. The os-instance-actions
API with the 2.21 microversion allows retrieving instance actions for a
deleted server resource. The os-migrations API takes an optional
instance_uuid
filter parameter but does not support
returning deleted migration records.
To allow clients to keep track of changes, the
changes-since
filter and changes-before
filter
displays items that have been recently deleted. Servers contain
a DELETED
status that indicates that the resource has been
removed. Implementations are not required to keep track of deleted
resources indefinitely, so sending a changes-since
time or
a changes-before
time in the distant past may miss
deletions.