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

Introduction

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

Terminology uses and extends the terminology and capabilities of OSLC Core Overview, 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.

References

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, 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]].

Basic Concepts

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.

Bootstrapping Discovery

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:

The URI could be for a ServiceProviderCatalog or context LDPC resource on which either static up-front or dynamic incremental discovery can be performed. Different server implementation architectures and extensibility mechanisms may require different approaches for discovering OSLC discovery resource URIs.

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.

Approaches to Discovery

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.

Service Provider concepts and relationships

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 OPTIONS or 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.

Updating Discovery Information

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.

Discovery Capabilities

The following sections define the OSLC Core discovery capabilities.

General Discovery Methods

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.

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

Servers SHOULD minimize the use of HTTP response headers on various HTTP operations as to avoid unnecessary additional response content for clients to consume.

This is also to avoid the complexity on server implementations that would be needed to provide such additional content.

Well-known URI Bootstrapping

An OSLC Server MAY serve a Root Services document at the /.well-known/oslc/rootservices.xml URI [[!WELL-KNOWN]] if the Server provides access to such a document. The Root Services document SHALL conform to the [[!ROOT-SERVICES]] specification. If no specific content type is requested, or if the requested content type is application/xml or application/rdf+xml, the server SHALL return the Root Services document using the RDF/XML-ABBREV format. Servers MAY return other formats in response to other requested content types.

An OSLC Server SHOULD serve a Service Provider Catalog at the /.well-known/oslc/sp-catalog URI if the Server provides access to such a document.

An OSLC Server MAY serve an LDP Container at the /.well-known/oslc/ldpc URI if the Server provides access to such a document.

An OSLC Server MAY use an HTTP redirect to a URI that satisfies the conformance clauses listed above in response to any request under /.well-known/oslc/ URIs.

An OSLC Server SHALL NOT serve documents on any vendor-specific URIs under /.well-known/oslc/ not defined in any official OSLC specification.

Resource Creation Discovery

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 POST method.

Servers MAY provide one or more creation factories to enable creation of new resources. Creation factories are LDPCs whose URI MAY be given in the oslc:creationFactory property of a Service resource.

The existence of an Accept-Post header 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 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.

In a response to Request-URI on an LDPC, servers SHOULD include Link headers with the relation-types set to rel="http://open-services.net/core#resourceType" and the Target URIs set to the rdf:type of 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.

Servers MAY include a RDF triple in resource response body of the form: <container-URI> oslc:resourceType <type-URI>. Clients SHOULD use the predicate oslc:resourceType when converting HTTP Link headers that have http://open-services.net/ns/core#resourceType as 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"

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

Servers MAY describe constraints enforced on resource representations through the http://open-services.net/ns/core#resourceShape property of a Creation Factory resource.

In a response to an HTTP OPTIONS, HEAD or GET method on a given Request-URI referencing an LDPC, servers SHOULD include a Link header 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 ResourceShapes, 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.

In a response to an HTTP POST or PUT method on a given Request-URI referencing an LDPC, servers SHOULD include a Link header 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 ResourceShapes, 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.

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 OSLC Resource Preview for resource preview discovery using the Link header or the Prefer header.

Resource User Interface Delegated Dialogs Discovery

See Delegated dialogs for resource selection and creation delegated UI discovery using the http://open-services.net/ns/core#selectionDialog or http://open-services.net/ns/core#creationDialog properties of a Service resource, or the Link header or the Prefer header.

Authentication Discovery

Clients SHOULD determine what authentication schemes a server supports by parsing and processing the challenge sent by the target server in response to a request for a protected resource.

Servers MAY provide OAuth configuration information in the OAuthConfiguration member of a ServiceProviderCatalog as described in .

Resource Constraints

This document applies the following constraints to the OSLC Core vocabulary terms.

Resource: ServiceProviderCatalog

Resource: ServiceProvider

Resource: Service

Resource: CreationFactory

Resource: QueryCapability

Resource: Publisher

Resource: PrefixDefinition

Resource: OAuthConfiguration