OSLC Core 3.0 Discovery

[Jim Amsden <jamsden@us.ibm.com>]

TC members,
Find attached my updates to discovery.html.
Since this is my first non-trivial contribution, I have not checked in
any changes. I'm not sure what the review procedure is for merging and
checking in, but wanted to get this out for quick review.

Here's what's covered in the changes,
and any remaining questions I had:


1. Should Steve and Sam continue to be listed as editors
even though they are likely no longer active given their contribution to
the content?

2. TODO: in Conformance section needs to be completed
with Discovery specific conformance. For example, are all OSLC Core 3.0
servers required to support discovery? I added some statements regarding
conformance.

2. Updated introduction and motivation sections with more
descriptive text. Changed the titles of the sections to be more descriptive
and consistent.

3. Section 5.2 Resource Creation Discovery - "The
existence of an Accept-Post header on an HTTP response to a given Request-URI
will indicate that both an HTTP POST is accepted for authorized
requests and which content types are support in the entity body of an HTTP
POST request". Should the will be MUST? There are numerous examples
of this.

4. Section 5.3 Checking for constraints for creation -
RECOMMENDS Resource Shapes which are not part of LDP. Is there any issue
with a RECOMMENDATION in an OASIS specification referring to non-OASIS
specifications such as the open-services.net OSLC 2.0 Resource Shapes.
I think this is OK, just checking.

5. If an LDP container supports many resource creationTypes,
and some of them are constrained and others are not, how are the link headers
for the creationType correlated with the constrainedBy link headers? 

The Link header with an appropriate context URI, a link
relation of http://www.w3.org/ns/ldp#constrainedBy,
and a target URI identifying a set of constraints would be returned in
response to a failed POST or PUT to a resource that violated the constraint.

These link headers may be included in the OPTIONS on the
LDP container as well. If the container supports multiple resources, then
should the constrainedBy relations include context IRIs (anchor parameter)
to identify the resource type that is being constrained?

If an LDPC supports creation of more than one creationType,
is a Link header with rel=“type” or rel="http://open-services.net/ns/core#creationType
creationType" required on the POST to indicate which type of resource
should be created? http://www.w3.org/TR/ldp/#ldpc-HTTP_POST 
doesn’t say this since its not really applicable to RDF resources since
they would already specify their rdf:type and non-RDF resources would likely
use MIME types. The Accept-Post header isn’t enough since the same content
type could apply to different resource types. Content type is the format
of the content, not its type.

Section 7.1.2 creationType seems to indicate that this
could be used on a Link-relation rel value for POST, but it seem like this
should be explicitly specified.

6. Added HTTPS Basic as required minimum authentication
and OAuth2 as SHOULD.

7. How does http://open-services.net/ns/core#creationType
relate to rdf:type? Should both be supported?

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575

Title: OSLC Discovery 3.0

This document outlines a common approach for HTTP/LDP-based server to be able to publish their RESTful API capabilities and how clients can discover and use them.

Stable Working Draft: received and incorporated TC feedback. (Almost) Ready for Public Review.

---

Introduction

A common problem with building interoperable solutions is having a mechanism for a client to introspect a server API or end-point to learn if the target application supports a set of capabilities. Client applications would then provide features based on what is discovered. For example, a person using a quality management tool wants to be able to record a bug in a bug tracking tool. The integration from the quality management tool will want to be able to do a number of things on behalf of the user and provide an optional integrated experience to streamline the users workflow. To do this, the quality management tool will need a means of discovering information about the bug tracking tool including: authenticating, knowing that the target tool is capable of receiving creation requests for bugs, whether it can be handled via a user interface, what fields are required and types of data, and also if the bug record can be pre-filled with some data from the test currently being executed.

OSLC Discovery 3.0 defines a capability allowing client applications a standard way to introspect servers to determine how to authenticate a user for accessing the server, what resource types the server supports, how to preview, select or create instances of those resources, and any constraints on resource creation or update. Discovery capabilities allow clients to adapt to, and integrate with different servers in order to support end user integration scenarios.

Terminology

Terminology is based on OSLC Core Overview [[OSLCCore3]], W3C Linked Data Platform [[LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], Hyper-text Transfer Protocol [[HTTP11]].

Discovery

The act of an OSLC Client to be able to determine if an OSLC Server supports a given capability. It also applies to applications that do not operate as a client or server, for example running within a web browser.

A conforming OSLC 3.0 client is a conforming [[LDP]] client that follows the rules defined in section Discovery Capabilities.

A conforming OSLC 3.0 server is a conforming [[LDP]] server that follows the rules defined in section Discovery Capabilities.

Motivation

Management and use of shared information in complex domains such as IT application lifecycle management and systems and software engineering often involve the integration of many data sources supported by tools developed by different vendors on different technical architectures, introduced at different times. Integrating these tools in order to support a wide range of evolving end user scenarios requires flexible and loosely coupled interactions between consumers and providers of this shared information. An important way of achieving this flexibility and loose coupling is to allow clients to incrementally discover the capabilities of any given server, and then adapt to what is discovered in order to maximize end user capabilities. Although a client would now know ahead of time what capabilities a given server might provide, they can know a standard means of discovering those capabilities, and can be developed in a way dynamically adapt to the discovered capabilities.

Some key usage scenarios that motivate a number of requirements for discovery.

Determine if the target tool supports:

• a certain authentication model (OAuth2, OpenID Connect, HTTPS Basic)
• creating resources with a given type
• user interface previews of a given resource
• user interface dialogs for creating or selecting resources of given types
• prefilling dialogs for resource creation
• describing the constraints on a resource creation or update request (allowable properties or values)

Additionally there is motivation to establish a common way for tools to support similar mechanisms so that each new capability doesn't introduce a new discovery model. It is also desired to have capabilities defined, whether within a standards development group or proprietary, to be able to leverage a similar approach to discovery.

Security concerns are also important when managing shared information across organization and tool boundaries. The specific security needs of any application however are difficult to predict. Experience has shown that this varaiability results in complexity for tool integration and therefore some standard mechanism for authentication discovery is highly desired.

The basis for how clients discover capabilities should be based on the methods established by [[LDP]] and [[HTTP11]].

Discovery Capabilities

There are various approaches for specifications to define how their capabilities could be advertised and how clients can efficiently discover what is available. The follow sections will provide guidance on approaches that should be used.

Choosing most effective methods

Clients SHOULD use HTTP OPTIONS to fetch various headers and other configuration information that MAY be exposed in the response content body.

Servers SHOULD minimize the use of HTTP response headers on various HTTP operations as to avoid unnecessary additional response content. This is also to avoid the complexity on server implementations that would be needed to provide such additional content.

Servers SHOULD only use LDPRrepresentations for additional discovery details that are not already available within HTTP response headers. It is also useful for scenarios where it would be valuable to have the discovery data readily available for purposes such as query.

Resource Creation Discovery

The existence of an Accept-Post header on an HTTP response to a given Request-URI will indicate that both an HTTP POST is accepted for authorized requests and which content types are support in the entity body of an HTTP POST request. Restating of [[LDP]] conformance clause about Accept-Post.

The existence of a Link: <http://www.w3.org/ns/ldp#Container>; rel="type" header on an HTTP response to a given Request-URI will indicate that the resource is a LDP Container. Restating conformance clause for [[LDP]] Link header and resource types.

Servers SHOULD include the target URI of a Link: <type-URI>; rel="http://open-services.net/ns/core#creationType" header on an HTTP response to a given Request-URI to indicate the type-URI (i.e.rdf:type) for the type of resources that can be created by the LDP Container. Note: since there is always some time between when the test is done and when the creation request is sent, and that there may be additional server enforced constraints on the creation resource representation, there is no guarantee that a future creation request will succeed.

				Link: <http://open-services.net/ns/cm#Bug>; rel="http://open-services.net/ns/core#creationType",
				      <http://example.com/vocab#Feature>; rel="http://open-services.net/ns/core#creationType"
				

The example above shows link headers returned in response to an HTTP OPTIONS request on container indicating the container can support the creation of Bug and Feature resources.

Servers MAY include a RDF triple in resource response body of the form: <container-URI> oslc:creationType <type-URI>.

Clients SHOULD use the predicate oslc:creationType when converting HTTP response headers for the same Link-relation type, into an RDF triple. This is to assist with scenarios where client applications may want to use the RDF representation in a query to locate LDP Containers that can be used to create the same resource types.

Example

The following example is an OPTIONS request on the /bugs/ resource.

				OPTIONS /bugs/ HTTP/1.1
				Host: example.come
				

The following responce indicates that POST is supported for creating resources while the Accept-Post header indictes Turtle and JSON-LD content types are supported. The type link header indicates the resource is an LDP BasicContainer. The createionType link hearders indicate which resource types are supported on POST. In this case the LDP Container advertises support for creating two types of resources: Bug and Feature.

				HTTP/1.1 204 No Content
				Date: Thu, 12 Jun 2014 18:26:59 GMT
				Allow: POST,GET,OPTIONS,HEAD,PUT
				Accept-Post: text/turtle, application/ld+json
				Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type",
					  <http://www.w3.org/ns/ldp#Resource>; rel="type"
				Link: <http://open-services.net/ns/cm#Bug>; rel="http://open-services.net/ns/core#creationType",
				      <http://example.com/vocab#Feature>; rel="http://open-services.net/ns/core#creationType"
				

Resource Creation and Update Constraints Discovery

In addition to the ways one can discover if a given OSLC Server supports creation of resources and for which types, it is helpful to understand if there are server-enforced constraints on the resource representation.

Servers SHOULD include the target URI of a Link: <constraints-URI>; rel="http://www.w3.org/ns/ldp#constrainedBy" header on an HTTP response to a given Request-URI to indicate the constraint-URI of a resource that defines the constraints about the to-be created resource representation against a LDP Container. The resource defined by constraint-URI is RECOMMENDED to be a machine-readible representation such as OSLC Resource Shape but MAY be some variant or other constraint document [[OSLCShapes2]]. See [[LDP]] section about server published constraints.

			Link: <http://example.com/shapes/bug>; rel="http://www.w3.org/ns/ldp#constrainedBy"
			

The link header in the example above would be returned on a POST or PUT to a resource of type <http://open-services.net/ns/cm#Bug> that violated the referenced constraint.

Servers MAY include a RDF triple in resource response body of the form: <container-URI> ldp:constrainedBy <shape-URI>.

Clients SHOULD use the predicate ldp:constrainedBy when converting HTTP response headers for the same Link-relation type, into an RDF triple. This is to assist with scenarios where client applications may want to use the RDF representation in a query to locate LDP Containers that are constraints by the same resource.

Resource User Interface Preview Discovery

See [[ResourcePreview]] sections on discovery using the Link header or the Prefer header.

Resource User Interface Delegated Dialogs Discovery

See [[Dialogs]] sections on discovery the Link header or the Prefer header.

Authentication Discovery

At a minimum, OSLC 3.0 servers MAY protect resources with HTTP Basic Authentication. OSLC Services that use HTTP Basic Authentication SHOULD do so only via SSL.

OSLC 3.0 servers SHOULD protect resources with OAuth2 Authentication utilizing OpenID Connect.

Shape

No shapes are defined in this specification.

RDF Vocabulary

Acknowledgements

Many thanks to the various OASIS Core TC members and other key contributors and reviewers.

Change History

The change history is up to the editors to insert a brief summary of changes, ordered by most recent changes first and with heading from which public draft it has been changed from.