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).

An object version resource has the following properties:

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.