OpenProvider
Editor's Draft 12 March 2010
- Editor:
- Richard Tibbett, Orange France SA
Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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:
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.
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.
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].
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.
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>
The XML Namespace URI for the XML data formats described in this specification is:
http://w3.org/2009/dap/openprovider/1.0
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.* |
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>
Describes an interface by which an OpenProvider Container can make requests for an external resource.
Parent: OpenProviderDescription
Attributes:
get
application/x-www-form-urlencoded
<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.
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.
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.
. (dot) delimiting characterorg.w3c.contacts.find
org.w3c.capture.captureVideo
org.w3c.filewriter.write
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.
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.
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.
HTML and XHTML documents may reference related OpenProvider description documents via the HTML 4.0 <link/> element [HTML40].
The following restrictions apply:
application/openproviderdescription+xml.api.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>
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.
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.
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:
chrome://capture/?id=35Edce9X (in this example we will say the OpenProvider Container implementation is Browser-based)Location header of the HTTP 302 Found response,
appending the unique callback address generated in Step 1 as an opcallback parameter to that request. 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.
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].
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.
No informative references.