This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

XXX REST API V.v

Introduction

This is the template for an OSLC domain specification. Text in italics forms instructions and guidance to the specification authors, and should be removed or replaced Plain text is sample or suggested text, and should be edited, replaced, or removed as appropriate..

Place some introductory text here, explaining the domain and its usage, including information about the scope of the services being defined, and the main scenarios or use cases being addressed by the specification. Subheadings may be added as appropriate. Below is some text from the SCM Specification V1 as a sample.

Software Configuration Management covers a wide range of practices, including tracking and controlling changes in the software using version control, building software and creating baselines, reporting on the contents of such builds and baselines, establishing traceability from requirements and change requests to software revisions, etc. This specification defines a set of RESTful interfaces using representations of resources, media types, the basic HTTP 1.1 methods and response codes. The capabilities of the interface definitions are driven by key integration scenarios and do not represent a complete set of operations on resources or resource types; service providers are neither required nor expected to expose their complete data model and application logic.

This version of the OSLC SCM specification describes services to browse the contents of baselines and change sets, and the version-controlled resources associated with those baselines and change sets. Clients may inspect the properties of these resources, and find differences between two such resources. No services are defined for the creation, modification, or deletion of resources.

Each of the following sections in the domain specification should contain a link to the corresponding section in the core specification. Sections that contain no additional information (that is, where the domain spec neither extends nor changes any of the requirements of the core specification) should be omitted.

Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Terminology

Define any required domain terminology here.

Base Requirements

Compliance

This specification is based on OSLC Core Spec DRAFT. OSLC XXX Vv providers MUST be compliant with both the core specification and this XXX specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

Specification Versioning

See OSLC Core Specification Versioning section.

Service providers that support the resource formats and services in this specification MUST use HTTP response headers of OSLC-Core-Version with a value of 1.0 and OSLC-XXX-Version with a value of V.v.

Namespaces

In addition to the namespace http://open-services.net/xmlns/oslc-core-1.0# with a default prefix oslc described in the core specification , this specification uses a domain-specific namespace of http://open-services.net/xmlns/oslc-XXX-1.0# with a default prefix of oslc_XXX.

Define any other namespaces uses in this domain specification.

Issue: should the domain-specific namespace URI end with '#'?

Resource Formats

See OSLC Core Resource Formats section.

XXX services MUST support both RDF/XML and JSON resource representations, and MAY support other representations.

Authentication

See OSLC Core Authentication section.

This section should contain any domain-specific extensions to the core OSLC requirements, such as mandating support for specific authentication protocols.

Error Responses

See OSLC Core Error Responses section.

This section should contain details of the XXX error responses.

OSLC XXX Resources

This section defines all the domain-specific resources. The specification should also cover how providers contribute additional resource types, and the namespaces that should be used. The section below is a sample resource type definition from the SCM specification.

A domain specification must also define any limitations on the http operations permitted on a resource - that is, which of GET, HEAD, PUT, POST, DELETE, etc., are supported, and any particular semantics of those operations.

Object Version

An object version is a resource representing a specific version of an object that is being controlled in the SCM system. Objects typically represent files and directories, but might also represent other resources such as requirements, models, assets, etc. Other OSLC SCM resource types are typically specific types or subtypes of object version. An object version is an abstract type; all SCM resource types are subtypes of object version. Note that some of these subtypes might be restricted to having a single version of each object (resource).

Object Version Resource
Name ObjectVersion
Suggested Prefix oscl_scm
Namespace URI http://open-services.net/xmlns/oslc-scm#
Type URI http://open-services.net/xmlns/oslc-scm#ObjectVersion
Version String oslc-scm-1.0

An object version resource has the following properties:

Prefixed Name Data type Occurs Extended Property? Title Description
OSLC Core properties
dc:title XMLLiteral zero-or-one No Title Title (reference: Dublin Core) of the resource represented as rich text in XHTML content; this SHOULD include only content that is valid inside an XHTML <span> element. SCM providers SHOULD use this property for a human readable number, name, or synopsis of the object version.
dc:description XMLLiteral zero-or-one No Description Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content; this SHOULD include only content that is valid and suitable inside an XHTML <div> element. SCM providers SHOULD use this property for a longer human-readable name or description of the object version.
dc:creator Complex - foaf:Person zero-or-many No Creator Creator or creators of resource (reference: Dublin Core)
dc:contributor Complex - foaf:Person zero-or-many No Contributor Contributor or contributors to resource (reference: Dublin Core)
dc:created DateTime zero-or-one No Created Timestamp of resource creation (reference: Dublin Core)
dc:modified DateTime zero-or-one No Modified Timestamp of the latest resource modification (reference: Dublin Core)
SCM properties
dc:identifier String exactly-one No Identifier An internal identifier, possibly assigned by the SCM system. This identifier MUST be unique amongst all currently existing object versions from this service provider.
dc:name String zero-or-one No Name A short name that is often used for an abbreviated identifier and used for presentation to end-users. Question: should we allow rich text here?
oslc_scm:owner Complex - foaf:Person zero-or-one No Owner The current owner of the object version (the person responsible).
oslc_scm:status String zero-or-one No Status A string indicating the current status of the object version.
oslc_scm:members Resource or Inline zero-or-many Yes Members A collection of elements indicating the object versions contained in this object version. Provision of this property may require a context to be supplied.

OSLC XXX Service Provider Capabilities

Service Discovery and Description

Core spec link not yet available

Resource Shapes

See Resource Shapes.

Service Provider Resource

See Service Provider Resource.

Creation Factories

See Creation Factories.

Query Capabilities

See Query Capabilities.

Delegated User Interface Dialogs

See Delegated UIs.

Media Types

Notices and References

Authors and Contact Information

List the names and companies of the authors here, plus contact information for the spec lead.

Authors of the OSLC XXX V.V Specification:

  • LeadName? (Company; OSLC XXX Lead)
  • Author1 (Company)
  • Author2 (Company)

Please address all enquires to the OSLC XXX Lead, LeadName? .

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the XXX V.V Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found here? .

Supporting Documents

This section may be omitted if there are no supporting documents - however, all domain specifications are strongly recommended to include a page of example requests and responses, showing at least some sample RDF XML. Links to other useful references not included elsewhere may also be included.

These non-normative documents do not form part of the specification, but provide examples and references, and document the use cases, design decisions, and rationale that led to the OSLC XXX V.V specification. In any discrepancy between what is described in these documents and the actual specifications, the specification prevails.

Document
Examples?
Scenarios and Use Cases?
Other Document?
RFC 999999
Topic revision: r2 - 01 Jul 2010 - 20:08:01 - DaveJohnson
 
This site is powered by the TWiki collaboration platform Copyright by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback