History   View   Links to this page 2014 May 9 | 11:58 am

Superseded by OASIS draft spec

Operations on Configurations

A configuration provider MUST support the following operations on configuration items (versioned concept resources):

  • HEAD: Retrieve information including the version resource URI (if any) about the state of a specified versioned concept resource in the context of a specified configuration.
  • GET: Retrieve the state of a specified versioned concept resource in the context of a specified configuration, where this operation returns zero or one version resources matching the required state.
  • PUT: Update the state of a specified versioned concept resource in a specified stream; this operation might or might not cause the creation of a new version of the resource.

A configuration provider MAY support the following operations on configuration items:

  • POST: Create the first version of a new concept resource, or a new version of an existing resource, in a specified stream
  • DELETE: Delete the current mutable version resource in a specified stream

A configuration provider MUST support the following operations on configurations:

  • HEAD and OPTIONS: Retrieve information about the configuration, including link headers compliant with the W3C Linked Data Platform specification indicating the non-member resource
  • GET: Retrieve the current state of the configuration.
  • DELETE a configuration; providers MAY refuse to delete configurations that are part of or referenced by existing baselines.
  • The BASELINE, STREAM, and COMPARE actions (see Actions)

A configuration provider MAY support the following operations on configurations:

  • Provide notification of changes to a configuration
  • Compare a configuration with another configuration; result format TBD.
  • Update a stream to correspond to a specified baseline; this is logically equivalent to deleting the stream and recreated it from the given baseline, but may be more efficient.
  • Merge a configuration into a stream; this operation updates the configuration to contain the latest revision of each concept resource in either of the two input configurations; handling of configuration specs and conflicts TBD.

A provider of aggregate configurations MUST also support the following operations:

  • PUT on a configuration to update the set of contained configurations
  • The SYNC action (see Actions)

Actions

Note: track evolving description of actions in other specs, including change management.

Actions are read-only properties of type Resource in a Configuration resource. The URI of such a reference property (“Action URI”) points to the Action resource that handles the actions. A resource can be updated by a HTTP POST to the Action URI. The request body of the HTTP POST MUST contain the URI of the configuration or configurations on which the action is to be performed. The request body MAY contain additional property values that control the action, or that are to be applied to the result of the action. A HTTP GET on the Action URI SHOULD return information about that action.

The Configuration resource representation SHOULD only include the actions that are applicable to the current state of the resource. If an action is attempted and the precondition for that action is not met, the request MUST respond with a 409 Conflict status code.

An attempt to update an action property explicitly in a PUT or PATCH request SHOULD be answered with a 409 Conflict HTTP status code. Their presence in a resource representation used for an update via PUT MUST NOT prevent the resource from being updated.

The Action resource specifies information about an action, such as a title and a description. It also can include a resource shape that can be used to give consumers hints about required field values for this action.

Prefixed Name Occurs Read-only Value-type Representation Description
dcterms:title exactly-one true XMLLiteral n/a Title (reference: Dublin Core) of the action.
dcterms:description zero-or-one true XMLLiteral n/a Description (reference: Dublin Core) of the action.
dcterms:identifier zero-or-one true String n/a A unique identifier for an action (reference: Dublin Core). Not intended for end-user display.
rdf:type zero-or-many true Resource Reference N/A | The resource type URIs, of which at least has the value http://open-services.net/ns/config#Action.

The available actions include:

Title Request body contents Result Description
BASELINE URI of stream for which a baseline is desired New or existing baseline Obtain a baseline for the state of a stream. If a baseline already exists that exactly matches the state of the stream, this existing baseline MAY be returned with a 200 (OK) response code. If a configuration contains member configurations that are not baselines, or components with configuration items that are not all in an immutable state, the service MAY fail with a 409 Conflict HTTP status code. Otherwise, a new baseline is created for each stream in the transitive closure of the member configurations, and the resulting top-level baseline is returned with a 201 (Created) status code.
STREAM URI of configuration for which a mutable copy is desired New stream Obtain a stream that is a copy of the given stream or baseline. If successful, the new stream MUST be returned with a 201 (Created) status code.
COMPARE URI of first configuration
URI of second configuration
Optional, URI of common ancestor		 TBD: comparison resource 2 or 3-way compare
SYNC URI of first aggregate configuration
URI of second aggregate configuration
URI of common baseline
Conflict resolution mode		 TBD: conflicts resource Synchronizes the contents of the two aggregate streams, adding, removing and updating member configurations in each to merge the changes from the common baseline. If the given ‘common baseline’ resource is not in fact an earlier baseline of both streams, the request MUST respond with a 409 Conflict status code. Success and conflict status codes TBD.