A common problem with building interoperable solutions is having a mechanism for a client to explore 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 defect in a change management 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 integrated experience to streamline the users workflow. To do this, the quality management tool will need to discover information about the change management tool including:
OSLC Discovery 3.0 defines a capability providing client applications a standard way to introspect servers to determine 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 determine what capabilities are provided by a server so they can adapt to, and integrate with different servers in support of end user integration scenarios.
Terminology uses and extends the terminology and capabilities of OSLC Core Overview [[!OSLCCore3]], W3C Linked Data Platform [[!LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], Hyper-text Transfer Protocol [[!HTTP11]].
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, and 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 may not 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 to dynamically adapt to the discovered capabilities.
Key usage scenarios that motivate a number of requirements for discovery include determining if the target tool supports:
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 variability 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]], and service provider resources defined by [[!OSLCCore2]].
The following sections introduce the basic concepts of OSLC discovery including how clients find discovery URIs, different approaches clients might use to discover server capabilities, and how server capabilities might be extended.
Discovery will always have to start with at least one discovery resource URI to bootstrap discovery on that server. Servers must provide some way for clients to learn about, find, or discover such LDPC URIs. For example, servers could provide such information:
OPTIONS *to return a ServiceProviderCatalog or link headers to root LDPCs describing the discovery capabilities offered
This specification specifies how servers respond to discovery requests through LDPC Link headers or ServiceProviderCatalog and/or ServiceProvider resources. It does not specify how servers organize their LDPCs, how they make distinguished LDPCs known to end users to start the discovery process, or how servers provide efficient access to discovery information that may be distributed over many LDPCs managed by the server. Servers may choose to support the OSLC Query capability on OSLC LDPCs and discovery resources in order to facilitate access to discovery information.
There are various approaches for how servers define and advertise their capabilities, and how clients can efficiently discover what is available. The following sections will provide guidance on approaches that should be used.
OSLC defines two broad approaches for clients to discover capabilities provided by a server, loosely categorized as "Static Up-Front" and "Dynamic Incremental".
Static Up-Front discovery, which is compatible with [[!OSLCCore2]], is an up-front or somewhat more static approach to discovery that utilizes ServiceProviderCatalog, ServiceProvider, and Service resources. Typically a client would perform discovery on startup by accessing the Services defined by any ServiceProvider resources the client might need. A client could also access one or more ServiceProviderCatalog resources in order to locate the available ServiceProvider resources. The client would then configure its capabilities based on what was discovered. In many, or possibly most instances, the ServiceProvider resources will be dynamically created by servers based on the state of the information they manage. Clients may choose to periodically refresh their capabilities by re-reading the ServiceProviders and adapting to the newly available services. Therefore this approach to discovery is not completely static, or up-front, but that does represent a possible common usage pattern.
Figure illustrates the Service Provider Catalog and Service Provider concepts and relationships. There are two resources defined: Service Provider Catalog and Service Provider, that provide the discovery information. There are also a set of local in-line resources that are provided inside these resources to define namespaces, OAuth configurations, contributors as well as services and their capabilities.
To allow clients to discover the RDF vocabularies supported by a server, those vocabularies should be referenced from the service discovery documents, and the vocabularies themselves and their constraining ResourceShapes should be readable RDF resources. The
oslc:domain property references a namespace that should resolve to the vocabulary document.
Dynamic Incremental discovery is a second approach that utilizes lazy or deferred discovery, getting just the information that is needed for any client capability when it is needed, and not getting information about server capabilities that might not ever be used. Clients typically utilize HTTP
HEAD methods on LDPCs and get discovery information from Link headers included in the HTTP response. This approach is more applicable for situations where the services provided by a server are changing rapidly as the result of resource creation or update, and clients will need to do incremental discovery before executing the next operations. This approach is also useful for clients that only need to do very specific things and are not necessarily involved in a long-running conversation with a server. Discovery in this case can be a simple HTTP
OPTIONS request on the required LDPC and the client can immediately complete its operation without needing to deal with potentially large discovery documents.
Both of these approaches are based on a uniform discovery capability. ServiceProviderCatalog, ServiceProvider and Service resources from [[!OSLCCore2]] are specific kinds of LDP Containers. The members of a ServiceProviderCatalog resource include ServiceProviderCatalogs and ServiceProvider LDPCs. ServiceProvider resource members include Service LDPCs. Each of these LDPCs have additional properties as defined by the OSLC vocabulary and shapes. This allows clients to use either approach to discover server provided OSLC capabilities, and maintains compatibility with [[!OSLCCore2]] while providing new, simple and flexible approaches to service discovery.
Servers may chose to support changes to their configurations in order to support adding new domains and services, extending existing domains and services, and/or integrating domains. This specification does not specify how servers provide extensibility mechanisms. Some possible approaches could include:
The ServiceProviderCatalog, ServiceProvider and Service shapes specify that much of the discovery information provided in these resource representations is read-only. Therefore clients accessing these resources cannot expect to change read-only properties via HTTP
PUT operation on the discovery resources as a means of updating server configurations. However, these constraints only apply to these particular discovery resource representations and do not prevent servers from providing other means of modifying their configuration information. These modifications would then be reflected in read-only properties in the discovery resource representations when they are accessed.
The following sections define the OSLC Core discovery capabilities.
The following clauses apply to all discovery capabilities including resource creation, resource preview, delegated dialogs for resource creation and selection, and resource constraints discovery. OSLC discovery capabilities may also apply to OSLC resources themselves, including LDPCs, and the discovery LDPC resources including ServiceProviderCatalog, ServiceProvider and Service resources. This allows servers to dynamically configure their capabilities, or provide users with a means of selecting the capabilities they need from those provided by a server.
OPTIONSto fetch various headers and other configuration information that may be exposed in the response content body from other HTTP methods.
Resource creation is done by sending an HTTP
POST to a URI that supports resource creation, providing the resource content in the entity request body. Clients can discover resources that support resource creation either through the
http://open-services.net/ns/core#creationFactory property of a Service in a ServiceProvider resource, or by using an
OPTIONS request on an LDPC to determine if it accepts the
oslc:creationFactoryproperty of a Service resource.
Accept-Postheader on an HTTP response to a given Request-URI indicates i) that an HTTP POST will be accepted for authorized requests and ii) what types of content are supported in the entity body of the HTTP POST request. Restating of [[!LDP]] conformance clause about
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]]
Linkheader and resource types.
Linkheaders with the relation-types set to
rel="http://open-services.net/core#resourceType"and the Target URIs set to the
rdf:typeof resources that can be created in the LDPC. Note: An LDPC can contain multiple types of resources, and the supported member types may change over time. 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.
<container-URI> oslc:resourceType <type-URI>. Clients SHOULD use the predicate
oslc:resourceTypewhen converting HTTP Link headers that have
http://open-services.net/ns/core#resourceTypeas the Link-relation ("rel" value) into RDF triples.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.
The following example is an OPTIONS request on the /bugs/ resource that demonstrates some of the discovery capabilities.
OPTIONS /bugs/ HTTP/1.1 Host: example.com
The response to this example request indicates that
POST is supported for creating resources while the
Accept-Post header indicates Turtle and JSON-LD content types are supported. The
"type" link header indicates the resource is an LDP BasicContainer. The
"resourceType" link headers 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. POSTing an entity request body that is not one of these types would result in an error.
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#resourceType", <http://example.com/vocab#Feature>; rel="http://open-services.net/ns/core#resourceType"
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. Clients can discover these constraints either through the
http://open-services.net/ns/core#resourceShape property of a Creation Factory resource, or by using
Link: <constraint-URI>; rel="http://www.w3.org/ns/ldp#constrainedBy"
header on an HTTP response to a given Request-URI.
http://open-services.net/ns/core#resourceShapeproperty of a Creation Factory resource.
GETmethod on a given Request-URI referencing an LDPC, servers SHOULD include a
Linkheader with the relation-type set to
rel="http://open-services.net/core#constrainedBy"and the Target URI set to the URI of a resource that defines constraints on the to-be created or updated resource representation in the LDPC. The resource referenced by Target URI is RECOMMENDED to be a machine-readable representation such as OSLC Resource Shape [[!OSLCCoreVocab]], but MAY be some variant or other constraint document. 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 an OPTIONS or HEAD request to a resource of type
<http://open-services.net/ns/cm#Bug> to provide the URI of the creation or update constraints.
PUTmethod on a given Request-URI referencing an LDPC, servers SHOULD include a
Linkheader with the relation-type set to
rel="http://open-services.net/core#constrainedBy"and the Target URI set to the URI of a resource that defines constraints that on the to-be created or updated resource representation in the LDPC that were not satisfied. The resource referenced by Target URI is RECOMMENDED to be a machine-readable representation such as OSLC Resource Shape [[!OSLCCoreVocab]], but MAY be some variant or other constraint document. 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.
<container-URI> ldp:constrainedBy <shape-URI>. Clients SHOULD use the predicate
ldp:constrainedBywhen 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.
See [[!ResourcePreview]] for resource preview discovery using the
Link header or
See [[!Dialogs]] for resource selection and creation delegated UI discovery using the
http://open-services.net/ns/core#creationDialog properties of a Service resource, or the
Link header or
This document applies the following constraints to the [[!OSLCCoreVocab]] vocabulary terms.
|01||07/06/2016||Jim Amsden||CSD was approved and published.|