Revision: Snapshots Using Resource State

This is one proposal for creating baselines in OSLC. For an overall description of the baseline scope and scenarios, and links to other proposals, see Baselines In Oslc.

This proposal defines a baselining capability where a service provider creates a snapshot of one or more resources by capturing the state of those resources. Compared to the other OSLC baseline proposals, it has the advantage of simplicity, but has a disadvantage in that the client has to determine the set of resources and service providers involved, rather than the providers themselves determining the dependencies.

There are two primary concepts: a camera capability for finding or making immutable snapshots, copies, or versions of resources or their states, and a Baseline resource that holds links to members of a baseline. The camera capability manipulates resources from a single OSLC provider; the baseline capability allows links to snapshots from multiple service providers.

The proposal also introduces the concept of a base resource URI: this is a URI that encompasses all possible states or versions of some resource. From the combination of a base resource URI together with sufficient context, a provider MUST return the appropriate state or version of that resource. If no context, or insufficient context, is provided, a provider MAY treat this as an error, or MAY return some representation of the base resource itself.

The Camera Capability

A server MAY provide a camera capability, to form or discover immutable snapshots, copies, or versions of its resources or their states. This capability is described by a Camera resource; the Camera resource is a factory through which new snapshots may be constructed, and providing information about snapshots previously made.

The oslc:Camera resource has the following properties, consistent with those of an OSLC Core Specification Resource Creation Factory:

oslc:Snapshot Resource

The oslc:Snapshot resource has the following properties:

Camera Usage and Results

1. A consumer requests an immutable snapshot of one or more resources belonging to a single service provider by a POST to the camera creation factory, following the normal OSLC conventions, with the rdfs:member properties in the POSTed snapshot resource containing the URIs of the resources for which a snapshot is requested. The result is the URI of an immutable oslc:Snapshot resource.
2. The snapshot request MAY fail, perhaps because one or more of the resources for which a snapshot was requested cannot be the subject of such a request. In this case, the provider SHOULD return sufficient information about the cause of the failure that a user can correct the situation.
3. If the request is successful, the resulting oslc:Snapshot resource has as members at least the set of resources in the original POST request.
4. A service provider MAY add to the snapshot additional dependent resources from the same service provider.
5. The specification for an OSLC domain MAY provide additional clarification and requirements determining the dependent members of a snapshot.
6. A service provider SHOULD provide a query capability that includes snapshots.

Using a Snapshot

An OSLC service that implements the camera service MUST support retrieval of a resource in the context of specified snapshot; the result of such a request MUST be a representation materially the same as the state of the requested resource as it was at the time the snapshot was taken. For example, read-only properties such as the time of last access may be different.

A snapshot is identified using the URI of the snapshot itself, or using the URI of a baseline containing a snapshot. When given a baseline, the service provider finds the member snapshot created by that same service provider; it is an error if there is no such snapshot, or if there is more than one. A snapshot provider MUST support passing the snapshot or baseline context to a resource request in each of the following ways:

• Appending oslc.snapshotMember query string and the URI (or base resource URI) of the requested resource to the URI of a snapshot or baseline;
• Passing the URI of a snapshot or baseline in the X-Oscl-Snapshot http header;
• Passing the URI of a snapshot or baseline in an X-Oscl-Snapshot cookie.

OSLC domain specifications MAY define additional or extended mechanisms for communicating baseline and snapshot context. In some domains the combination of a base resource URI and a baseline or snapshot URI might not be sufficient to identify a unique resource state - for example, in SCM, a configuration might contain two different versions of the same base resource in different paths within that configuration, as when a dependent library was rebuilt to fix a last-minute defect, but only selected portions of the complete configuration were updated to use that new library version to reduce the risk associated with making last-minute changes. In this case, it might be convenient to allow a URI to be constructed combining in some manner the snapshot context, the base resource identity, and the relative path to that resource within the SCM snapshot.

oslc.snapshotMember ::= "oslc.snapshotMember=" uri_ref_esc

Examples:

GET http://example2.com/oslc/baseline/1234?oslc.snapshotMember=http://example1.com/oslc/someresource

GET http://example2.com/oslc/baseline/1234/scmSnapshot1?oslc.snapshotMember=http://examplescm.com/oslc/configuration1/path/to/someresource

GET /oslc/someresource
Host: http://example1.com
X-Oscl-Snapshot: http://example2.com/oslc/baseline/1234

GET http://example1.com/oslc/someresource
Cookie: X-Oscl-Snapshot=http://example2.com/oslc/baseline/1234

OSLC Baseline Resource

This baseline resource is adapted from the OSLC SCM baseline, for a more general usage across OSLC:

Baseline Creation and Usage

1. Clients create a Baseline resource by creating a HTTP POST request with the initial set of baseline properties to the baseline creation factory URI.
2. Clients may add oslc:Snapshot resources as members of a Baseline resource when that baseline is initially created using POST, or while it is under construction using PUT updates. Service providers MAY support a partial update protocol.
3. The snapshots added to a baseline do not have to be all from the same service, service provider, or OSLC domain.
4. An OSLC baseline service MUST provide a Baseline creation factory, and SHOULD provide a query capability that includes Baselines.
5. A baseline service provider MAY also implement the camera capability. In such a service provider, baselines may be composed from snapshots of other baselines and other snapshots.

Note that that it is possible for a client to “front-end” documents or service providers that do not currently support snapshots to add thise capability. For example, simple Word or Excel documents can be added to baselines by creating a wrapper to copy the required documents or resources, create an oslc:Snapshot resource linking to those now-static copies, and add this new snapshot to an oslc:Baseline. It would also be possible to define and create a new service providing this wrapping capability.

Baseline membership traversal

Clients can navigate from baselines to their oslc:Snapshot members. This specification does not define the link structure within those snapshots: some providers might add as snapshot members all the resources in the snapshot, or just direct members, with other snapshotted members linked to those direct members. An OSLC domain specification MAY provide additional details about snapshot membership.

Best Practices for Linking

A link between OSLC resources MAY be in the form of a URI qualified by the baseline or snapshot context. While such version-specific links might be appropriate in some cases, in general they should be avoided as they reduce flexibility. For example, if a test case is linked directly to a requirement in the context of a given baseline, it is forever linked only to that specific state of the target requirement. It might be more appropriate to create the link between the test case and the base resource URI for the requirement, and to express the baseline context using the http header or cookie techniques. This allows the link to be remain valid for subsequent baselines of the test cases and requirements.

Comments

From Ian Green: This proposal leaves somewhat unconstrained the relationship between a resource and an immutable snapshot of that resource. The mention of “base URI” seems to suggest that the rdfs:member URIs of a snapshot might have something in common with the URIs of the things they are snapshots of, but the spec does not require this, nor provide a mechanism for the user to derive one from the other. Should a client be able to determine that a resource and one of its snapshots are so related?

Also from Ian: The proposal allows for the creation of snapshots of baselines, and hence the composition of baselines of baselines. Is this extra complexity necessary?

From Martin Nally: I think the “Baseline membership traversal” paragraph is too complex. I think we should go one of two ways 1) make the snapshot totally opaque – you can’t get a list of its members 2) make it list all its members in a flat list.

– Main/NickCrossley - 20 Jul 2011

Should the snapshot creation process use long-running operation techniques, such as returning a status resource that the client must poll until completion, whereupon the URI of the snapshot resource becomes available?

– Main/NickCrossley - 04 Aug 2011

Are we comfortable with the proposed terminology? The term ‘snapshot’ as used here might correspond to existing ‘baseline’ artifacts in current tools.

– Main/NickCrossley - 04 Aug 2011