SIF - Changes Since (http GET)

Events are already supported since the initial release of SIF 3. SIF Events are most commonly supported in Brokered environments but unlikely to be available in DIRECT environments. To enable a consumer to request changes since a “given point” in a DIRECT environment the “Changes Since” functionality is being added to SIF 3.2. The "given point" can be any opaque marker that indicates a point since the last changes have been requested. That opaque marker can be a timestamp, a version number, an offset etc. It is entirely up to the provider to determine what this opaque marker is. The important thing is that it is the provider who will return changed data (payload) and the next valid opaque marker (HTTP Header) to the consumer in the response to a "changes since" request.
IMPORTANT: "Changes Since" functionality is only applicable for OBJECT services. In other words changes since is not supported for any other service type such as SERVICEPATH, FUNCTION, UTILITY etc.

REST Call (Consumer)

For a consumer to retrieve changes since a given point it simply issues the following request to the request connector of the standard Object provider (example for xStudents):

GET .../xStudents?changesSinceMarker=<opaque_marker_for_students>

Note the “changesSinceMarker” URL query parameter. It must be noted that there will be a different opaque marker for each object type. The consumer is expected to track them individually.

“Changes Since” requires this additional URL query parameter to indicate that the consumer requests a “Change Since” rather than a standard query. The actual REST call is conveyed as a HTTP GET and supports all other standard HTTP headers. Paging is allowed but sorting and filtering (“where” clauses as for dynamic queries) is not allowed and must be ignored by the provider if given by the consumer.

“changesSinceMarker” Management

The changesSinceMarker is given to the consumer in two ways one being the HTTP HEAD method the other being the response to the changes since request. Both of these are detailed below.

HTTP HEAD

The first method to retrieve the “changesSinceMarker” is through the HTTP HEAD method to the Object Provider. If the Object Provider supports the “ChangesSince” functionality for the given object then it is expected to return the “changesSinceMarker” as a HTTP Header in the response. If the provider does not return that HTTP header then the consumer must assume that “Changes Since” functionality is not supported for the given Object Type/Service. It is expected that the consumer calls this method when it first joins the SIF environment and before it performs and initial sync of all data.
Response to “Changes Since” request
Once a consumer has retrieved the “changesSinceMarker” through the HTTP HEAD call, has performed a full sync, it is assumed that the consumer will, at regular intervals, request “changes since” with the REST call listed earlier in this document. As part of the response to such a call the provider must return the new “changesSinceMarker” to the consumer as a HTTP Header field in the following two cases:

- If the consumer has not provided any paging info, indicating that the response holds all changes for the given object type, then the provider must return the new “changesSinceMarker” as a HTTP Header field. The consumer will use that new value in the next “Changes Since” call.

- The consumer has provided paging info. In this case the provider must return the new “changesSinceMarker” as a HTTP Header field in the response of the first page. The consumer is expected to store that new value. It will still request the remaining pages with the original “changesSinceMarker”, though. Once all changes have been received it will use the new “changesSinceMarker” in the next “Changes Since” call.
  Note: In the case of ‘paging’ it is expected that the provider will also return the navigationId HTTP Header since it is highly likely that the consumer will come back and ask for more pages until there are no more. The consumer would provide that navigationId in each request as a HTTP Header or URL Query parameter.

Payload Interpretation

The response payload to a "changes since" request is always a collection of the same objects (i.e. xStudent). The payload can be empty if there are no more changed data (HTTP Status 204 - No Content). Because objects have no element that indicates the change type there is a need to interpret the payload as listed below to determine the actual change type:

If the refId/uuid of a particular object in the response payload does not exist in the consumer's data store it must be assumed to be NEW (i.e. created).
If the refId/uuid of a particular object in the response payload does exist in the consumer's data store it must be assumed to be UPDATED (i.e. changed). It is important to note that the full object is returned not a partial object because there is no way to indicate if the update is partial or full.
If a particular object in the response payload contains the refId/uuid only the consumer must assume that object to be DELETED.

Provider Registry & ACLs

“Changes Since” is considered as standard OBJECT queries and therefore no other service type in the provider registry is required. If the ACL for a particular object service lists the ‘QUERY’ right as ‘APPROVED’ then a consumer can issue “Changes Since” requests. If a provider of an object type service does not support the "Changes Since" functionality then it must return the standard HTTP status code 400 (Bad Request). The "Changes Since" functionality is optional and not mandatory for a provider. Note that a consumer can “query” the Object provider with the HTTP HEAD call to determine if an Object provider supports the “Changes Since” functionality before issuing “Changes Since” requests.