W3C

OpenProvider

Editor's Draft 12 March 2010

Editor:
Richard Tibbett, Orange France SA

Abstract

The OpenProvider format and associated processing rules allow for Device API implementations to discover, interpret and interact with web-based service providers according to well-defined JSON/XML-based inputs and outputs depending on the particular Device API requested by a web application.

This proposal collectively provides four elements for consideration:

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is for review by the Device APIs Working Group and is subject to change without notice. This document has no formal standing within W3C. Please consult the group's home page and the W3C technical reports index for information about the latest publications by this group. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

The W3C Device APIs and Policy Working Group is currently defining APIs to allow web applications to request and obtain access to device-orientated functionality. In the course of this activity, it has been noted that for some APIs it is not a requirement that the term "device" be used in a strict sense to mean to and from a user's local device but to encorporate the ability to interact with providers beyond the user's physical device, such as with web-based API providers and/or local web-based implementations of Device APIs.

While the primary intention to date has been towards sending and receiving data from a user's physical device, this specification proposes a format to allow web providers, both large and small, to define and distribute their API information in an open way in order to allow W3C DAP implementors and implementations to obtain, interpret and interact with these defined web providers in a similar way to native implementations - through the Javascript APIs defined by the W3C DAP WG to date.

The Javascript APIs defined by the W3C DAP WG are in principle an abstraction away from any one implementation strategy - not strictly requiring any protocol-based implementation. It is noted that interaction with native Device APIs by means other than web-based protocols is not in scope of this document, unless access to those native Device APIs is implemented as a local web-based service in which case the rules defined within this specification will apply.

OpenProvider documents can be written by any party but only become active when installed by a user in their respective OpenProvider Container. An OpenProvider Container is capable of reading OpenProvider documents and is responsible for directing the interaction with service endpoint(s) according to the requested OpenProvider "Url" rel value. An OpenProvider Container would be typically implemented in the UA itself.

An OpenProvider Container requires well-defined interaction with web-based service providers both for sending the details of a web-application originated request to a user-selected OpenProvider Url and for receiving responses from that OpenProvider depending on the context of the interaction.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

3. OpenProvider description document

An OpenProvider document describes the public endpoints of a service provider so that the provider can be queried as if it were a local device-based service.

The plural OpenProviders refers to a collection of one or more OpenProvider documents.

3.1 Examples

The following is an example of an OpenProvider document describing video capture, audio capture and image capture endpoints for an example provider.

<?xml version="1.0" encoding="UTF-8"?>
<OpenProviderDescription xmlns="http://w3.org/2009/dap/openprovider/1.0" 
                         xmlns:capture="http://w3.org/2009/dap/capture"/>
  <ShortName>Example Inc.</ShortName>
  <Description>Capture video, audio from the local device and images 
	from your Example.com account</Description>
  <Url type="application/json" rel="org.w3c.capture.captureVideo"  
	template="http://example.com/api/video/get?limit={capture:limit?}&
	  duration=(capture:duration?)"/>
  <Url type="application/json" rel="org.w3c.capture.captureAudio" 
	template="http://example.com/api/audio/get?limit={capture:limit?}&
	  duration=(capture:duration?)"/>
  <Url type="application/json" rel="org.w3c.capture.captureImage"
	template="http://example.com/api/image/get?count={capture:limit?}"/>
  <OutputEncoding>UTF-8</OutputEncoding>
  <InputEncoding>UTF-8</InputEncoding>
</OpenProviderDescription>

The following is an example of an OpenProvider document describing the public address book service available from an example provider.

<?xml version="1.0" encoding="UTF-8"?>
<OpenProviderDescription xmlns="http://w3.org/2009/dap/openprovider/1.0" 
                         xmlns:contacts="http://w3.org/2009/dap/contacts"/>
  <ShortName>Example Inc.</ShortName>
  <Description>Interact with your Example.com Address Book</Description>
  <Url type="application/json" rel="org.w3c.contacts.find"
     template="http://example.com/addressbook/1.0/find.php?name={contacts:name}"/>	  
  <Url type="application/json" rel="org.w3c.contacts.create"
     template="http://example.com/addressbook/1.0/create.php" method="POST" 
        enctype="application/x-www-form-urlencoded"/>	  
  <Url type="application/json" rel="org.w3c.contacts.save"
     template="http://example.com/addressbook/1.0/save.php" method="POST" 
        enctype="application/x-www-form-urlencoded"/>		  
  <Url type="application/json" rel="org.w3c.contacts.remove"
     template="http://example.com/addressbook/1.0/remove.php?id={contacts:id}"/>		  
  <OutputEncoding>UTF-8</OutputEncoding>
  <InputEncoding>UTF-8</InputEncoding>
</OpenProviderDescription>

3.2 Namespace

The XML Namespace URI for the XML data formats described in this specification is:

http://w3.org/2009/dap/openprovider/1.0

3.2.1 Contextual Namespaces

An OpenProvider XML Namespace must be used to associate Device API parameters to their associated Device API context.

All Device API specific elements, attributes, and parameters used in a OpenProvider Url element must be associated with a well-defined OpenProvider XML Namespace.

The following OpenProvider XML Namespace tokens are defined for Device APIs. The Associated Valid Device API identifier indicates on which OpenProvider Url element the parameters contained within the OpenProvider XML Namespace can be used.

OpenProvider XML Namespace token Associated OpenProvider "Url" rel value
xmlns:contacts="http://w3.org/2009/dap/contacts"org.w3c.contacts.*
xmlns:calendar="http://w3.org/2009/dap/calendar"org.w3c.calendar.*
xmlns:capture="http://w3.org/2009/dap/capture"org.w3c.capture.*
xmlns:filewriter="http://w3.org/2009/dap/filewriter"org.w3c.filewriter.*
xmlns:gallery="http://w3.org/2009/dap/gallery"org.w3c.gallery.*
xmlns:messaging="http://w3.org/2009/dap/messaging"org.w3c.messaging.*
xmlns:systeminfo="http://w3.org/2009/dap/system-info"org.w3c.systeminfo.*

3.3 Description elements

3.3.1 The "OpenProviderDescription" element

The root node of any OpenProvider document.

Parent: none
Requirements: The element must appear exactly once as the root node of the document.

<OpenProviderDescription xmlns="http://w3.org/2009/dap/openprovider/1.0/">
    <!--- ... --->
</OpenProviderDescription>

3.3.2 The "Url" element

Describes an interface by which an OpenProvider Container can make requests for an external resource.

Parent: OpenProviderDescription
Attributes:

type
The MIME type of the resource being described.

Restrictions: The value must be a valid MIME type.
Requirements: This attribute is required.
rel
The role of the resource being described in relation to the description document.

Restrictions: Contains a space-delimited list of valid OpenProvider "Url" rel value tokens.
Requirements: This attribute is required.
template
The endpoint URL template to be processed according to the OpenProvider URL template syntax.

Requirements: This attribute is required.
method
The HTTP method by which to communicate with the endpoint.

Restrictions: Must be a valid HTTP request method, as specified in [HTTP11].
Default: get
Requirements: This attribute is optional.
enctype
Contains a string that identifies the content encoding the search client should use to perform the request.

Default: application/x-www-form-urlencoded
Requirements: This attribute is optional.

Requirements: This element must appear at least once.

<Url type="application/json" rel="org.w3c.capture.captureVideo"
	  template="http://localhost:3421/capture/stream"
	  method="POST" enctype="application/x-www-form-urlencoded"/>

All elements of an OpenProvider document will be described here.

3.4 URL templates

Device API method parameter names can be used in OpenProvider URL templates to provide conventional query parameter names.

3.4.1 URL template syntax

The OpenProvider URL template format can be used to represent a parameterized form of the URL by which a resource is queried.

The syntax for this element must conform to any of the techniques provided in [URI].

An OpenProvider Container is used to process the URL template and attempt to replace each instance of a template parameter, generally represented in the form {name}, with an OpenProvider Input Parameter value provided from a requesting web application at runtime.

3.4.1.1 Substitution rules

The provider client must replace every instance of a template parameter with a value before the resource request is performed.

If a provider wishes to indicate that a template parameter is optional and can be replaced with the empty string, then the "?" notation should be used as described in Optional Parameters.

3.4.2 Parameter namespaces

All template query parameters in the template must be associated with an XML namespace name via a well-defined OpenProvider XML Namespace prefix.

3.4.3 Optional parameters

The search server can use the "?" flag when requesting a Device API-based parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the extension.

3.5 URL "rel" values

An OpenProvider "Url" rel value represents the relationship of an OpenProvider Url element to a well-defined Device API. A valid OpenProvider "Url" rel value consists of three parts:
org.w3c.contacts.find
org.w3c.capture.captureVideo
org.w3c.filewriter.write

3.5.1 Device API identifiers

A Valid Device API identifier is included as part of a valid OpenProvider "Url" rel value.

The Valid Device API identifier tokens and their application to given OpenProvider XML Namespace tokens are defined in Contextual Namespaces.

3.5.2 Device API methods

A Valid Device API method is included as part of a valid OpenProvider "Url" rel value.

A Valid Device API method is a method that is defined and available in the corresponding specification of a Valid Device API identifier. A * (wildcard) value may be used to indicate that the Url element is the endpoint for all requests corresponding to the given Valid Device API identifier.

3.6 Autodiscovery

Providers that publish OpenProvider description documents can assist OpenProvider Containers in the discovery of OpenProvider interfaces through the use of "link" elements.

Providers that support OpenProvider should include a reference to the related OpenProvider description document on each relevant page.

3.6.1 Autodiscovery in HTML/XHTML

HTML and XHTML documents may reference related OpenProvider description documents via the HTML 4.0 <link/> element [HTML40].

The following restrictions apply:

  • The "type" attribute must contain the value application/openproviderdescription+xml.
  • The "rel" attribute must contain the value api.
  • The "href" attribute must contain a URI that resolves to an OpenProvider description document.
  • The "title" attribute may contain a human-readable plain text string describing the provider.
  • The HTML <head/> element should include a "profile" attribute that contains the value http://w3.org/2009/dap/openprovider/1.0.

Example of an HTML document that includes OpenProvider autodiscovery link elements:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"/>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
  <head profile="http://w3.org/2009/dap/openprovider/1.0">
    <!--- ... --->
    <link rel="api"
          type="application/openproviderdescription+xml" 
          href="http://example.com/contacts-find.xml"
          title="Example.com Address Book access" />
    <link rel="api"
          type="application/openproviderdescription+xml" 
          href="http://example.com/imagesearch.xml"
          title="Example.com Photos access" />
    <!--- ... --->
  </head>
  <body>
    <!--- ... --->
  </body>
</html>	

4. OpenProvider processing

An OpenProvider Container is the client that interacts with service provider resources defined in any given OpenProvider document.

An OpenProvider Container responds to two modes of operation for interacting with OpenProviders: Non-Interactive Provider processing and Interactive Provider processing.

4.1 Non-Interactive Providers

A Non-Interactive Provider is when an OpenProvider resource is capable of returning an OpenProvider response directly from the template defined in an OpenProvider URL element.

A Non-Interactive Provider can be inferred when a resource provides a HTTP 200 OK response, as defined in [HTTP11], to an initial URL element request.

On receipt of a HTTP 200 OK response, the OpenProvider Container must parse the response body, according to the Rules for Processing Non-Interactive Responses.

4.2 Interactive Providers

An Interactive Provider is when an OpenProvider resource is not capable of returning an OpenProvider response directly from the template defined in an OpenProvider URL element - perhaps because the Provider expects some interaction from the user (e.g. User Authentication) before a response can be returned.

An Interactive Provider can be inferred when a resource provides a HTTP 302 Found response, as defined in [HTTP11], in reply to an initial URL element request.

On receipt of a HTTP 302 Found response, the OpenProvider Container must:

  1. Generate a unique callback address on which to await feedback from the Interactive Provider. e.g. chrome://capture/?id=35Edce9X (in this example we will say the OpenProvider Container implementation is Browser-based)
  2. Repeat the given request with the original parameters to the URL provided in the Location header of the HTTP 302 Found response, appending the unique callback address generated in Step 1 as an opcallback parameter to that request.
  3. Let the OpenProvider Container display the subsequent HTTP response from the Interactive Provider in a new browser tab.

When the unique callback address is called by the provider following any required user interaction the OpenProvider Container must parse the callback request body received, according to the Rules for Processing Interactive Requests.

5. OpenProvider request elements

OpenProvider request elements defines the formatting on which to communicate with web-based OpenProvider URL endpoints.

OpenProvider Containers send well-defined request elements to a web-based Provider URL in order to communicate any runtime, web-application originated, request parameters.

It is intended that this section will refer to a well-defined WebIDL to XML/JSON binding specification in order to represent the expected formatting of Provider requests according to the invoked OpenProvider "Url" rel value. The concept of a WebIDL to XML/JSON binding has been raised on the W3C public-device-apis mailing list on a number of occasions [1] [2] [3]. .

Nothing quite suitable yet exists for this, although the editor expects that a specification similar to the OMG IDL XML Valuetype Language Mapping specification would provide the blocks on which this issue could be resolved without requiring the explicit XML/JSON declaration required per request.

It has also been suggested that this is also an outstanding issue in the Powerbox proposal [4].

6. OpenProvider response elements

OpenProvider response elements define the formatting on which a Provider can communicate service responses to an OpenProvider Container in both Interactive Provider and Non-Interactive Provider scenarios.

OpenProvider Containers expect well-defined response elements from a web-based Provider URL in order to process such responses and communicate them to web-applications as response callback parameters.

It is intended that this section will refer to a well-defined WebIDL to XML/JSON binding specification in order to represent the expected formatting of Provider responses according to the requested OpenProvider "Url" rel value. The concept of a WebIDL to XML/JSON binding has been raised on the W3C public-device-apis mailing list on a number of occasions [1] [2] [3]. .

Nothing quite suitable yet exists for this, although the editor expects that a specification similar to the OMG IDL XML Valuetype Language Mapping specification would provide the blocks on which this issue could be resolved without requiring the explicit XML/JSON declaration required per response.

It has also been suggested that this is also an outstanding issue in the Powerbox proposal [4].

The Rules for Processing Non-Interactive Responses refers to the OpenProvider Container JSON/XML-to-WebIDL processing rules for responses from any Non-Interactive Provider resources.

The Rules for Processing Interactive Requests refers to the OpenProvider Container JSON/XML-to-WebIDL processing rules for callbacks provided from any Interactive Provider resources.

A. References

A.1 Normative references

[HTML40]
Ian Jacobs; David Raggett; Arnaud Le Hors. HTML 4.0 Specification. 24 April 1998. W3C Recommendation. URL: http://www.w3.org/TR/1998/REC-html40-19980424
[HTTP11]
R. Fielding; et al. Hypertext Transfer Protocol - HTTP/1.1. June 1999. Internet RFC 2616. URL: ftp://ftp.isi.edu/in-notes/rfc2616.txt
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[URI]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifiers (URI): generic syntax. January 2005. Internet RFC 3986. URL: http://www.ietf.org/rfc/rfc3986.txt

A.2 Informative references

No informative references.