You are here: MyURC.org > TR > res-serv-http1.0-20090429 > Draft

Resource Server HTTP Interface 1.0 (DRAFT)

Abstract

This document specifies how resources can be queried and retrieved from a resource server via HTTP.

Status of this Document

This is a public Draft Technical Report, developed by the editor, hereby made available for review by URCC members and the public.

Comments on this document should be sent to the editor.

Publication as a Draft Technical Report does not imply endorsement by the URCC membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Open Issues [to be removed before final release]

1. The meaning of weights between 0 and 1 is not clearly defined (implementation-specific right now).
2. All properties are implicitly ANDed in a resource query. Should we allow for more complex queries, with AND/OR structure?
3. Define namespace(s) for resource query and response language?

Change Log [to be removed before final release]

NOTE: The change log is in reverse chronological order.

2009-04-29 Gottfried Zimmermann:

• Allow for multiple queries in one HTTP POST request, and multiple resources in response. Take care of expiration of previous requests.

2008-08-14 Gottfried Zimmermann:

• Initial release as draft for review. 

Table of Contents:

1. Requirements

1. The resource server shall be available at a fixed domain name.
2. Two alternate usage modes: anonymous, authenticated.
3. Two steps for downloading a resource: Resource query, resource retrieval.
4. Resource query shall be available via HTTP GET/POST (anonymous) and HTTPS POST (anonymous or authenticated).
5. Resource retrieval shall be available through HTTP GET/POST (anonymous) and HTTPS POST (anonymous or authenticated).
6. A request for a resource shall contain a list of properties (optionally including descriptors) and values. The list of properties is open. Which set of properties are applicable for a resource query depends on the resources' properties being queried.
7. Property names shall be full (absolute) URIs, consisting of a namespace identifier and a property name.
8. The response (result) of a request for resource shall indicate the appropriate MIME type through the Content-Type field of the HTTP header.

2. Resource Server URL

A resource server shall have a fixed URL, using the HTTP scheme and a domain name (e.g. http://myurc.org/resserv/).

In the remainder of this document, the resource server URL is referenced as http://res-serv-url/.

3. Resource Properties

Resources are stored on the resource server with their metadata. Metadata is expressed in the form of resource properties. A resource property name shall be a string representing a full (absolute) URI [RFC 3986], to be understood as a concatenation of a namespace identifier and a property name. Note that specific encoding rules may apply when using a property name in a given context (for example as URI component, or inside XML content).

Property names shall be case-insensitive. The value of a property shall be a string.

One property may occur multiple times for a resource, but with different values, thus expressing that all values apply to the resource.

A property may have one or multiple descriptors, allowing for variations of the property along the descriptors' value spaces (e.g. language codes). The purpose of a descriptor is to find the most relevant property among multiple properties with the same name. A descriptor shall be a string (e.g. "lang" for language), and its value also a string (e.g. "en" for the English language code).

A human understandable description should be available for each property at its URI which should be resolvable. For example, a property can be described within an RDF schema file, with the property's URI consisting of the location of the RDF schema file and the property name as fragment identifier (e.g. "http://myurc.org/ns/res#forTargetInstance" [RES Namespace] is described in the RDF schema file at http://myurc.org/ns/res).

4. Resource Query

A client can ask the resource server to send a list of resource descriptions (including a URL for download) that meet specific criteria. This is called a "resource query".

Note: If the client knows the URL of a resource, it can immediately retrieve it (see "resource retrieval" below). However, metadata (descriptions) on a resource can only be obtained through a resource query.

A resource server shall offer resource queries through HTTP GET, HTTPS GET and HTTPS POST.

4.1. Resource Query: HTTP GET Request

An HTTP GET request shall be made to http://res-serv-url/query?prop1=value1&prop2=value2 whereby

• prop1 and prop2 may be any property name, either as full URL (at least one colon ':' character included) or as property without namespace (no colon ':' character included), in which case the default namespace http://myurc.org/ns/res# shall be assumed.
• value1 and value2 may be any string indicating a desired value for the property.
• The request shall contain one or more property-value pairs.

Note: Reserved characters (see RFC 3986, section 2.2) shall be percent-encoded (see RFC 3986, section 2.1), when contained in a property name or value. Common programming languages offer encoding functions for URL components, for example the global function encodeURIComponent() in JavaScript.

The HTTP GET request header should not contain an "Authorization" header [RFC 2617]. If it contains one, the server shall ignore it.

Note: The HTTP GET request is a simplified request type and does not support the following advanced features: specify a property descriptor, specify the first index or number of returned elements in the resource list. Please refer to section Resource Query: HTTP(S)POST Request if you want to use any of them.

4.2. Resource Query: HTTP(S) POST Request

An HTTP POST request shall be made to http://res-serv-url/query (unsecure connection) or https://res-serv-url/query (secure connection), with an XML-encoded message body in the following format:

<queries>
  <query start="firstindex" count="number">
    <prop name="prop1" val="value1" wgt="weight1">
      <descriptor name="desc1" val="dvalue1" />
      <descriptor name="desc2" val="dvalue2" />
    </prop>
    <prop name="prop2" val="value2" wgt="weight2" />
  </query>
  <query ref="referenceId" start="firstindex" count="number" />
</queries>

Whereby:

• The message body shall comply to [XML 1.0]. It should not contain any namespace declaration.
• The encoding shall be UTF-8 [UCS].
• The resource server should respect the header fields of the HTTP(S) request [RFC 2616].
• For HTTPS POST requests, a resource server may require basic authentication in the message header. If required, but not present in the request, the server shall respond with error code 401 Unauthorized [RFC 2616].
• <queries> shall occur exactly once.
• <query> shall occur 1 or more times under <queries>.
  • The 'ref' attribute may be present. If present, it shall specify a query reference identifier that had been assigned by the server in a previous response (see section Resource Query: Response). If present, no 'start' or 'count' attribute shall occur on the same <query> element.
  • The 'start' attribute may be present. If present, it shall specify the index of the first element in the matching resources list (index starting with 1). If not present, it shall default to "1".
  • The 'count' attribute may be present. If present, it shall specify the requested number of matching resources. The special value of "all" indicates that all resources are requested. Note that the server may still not deliver all resources due to time or bandwidth issues. If not present, it shall default to "1".
  • If neither 'start' nor 'count' is present, a best match is requested. In this case, any returned <response> element shall not contain the attribute 'ref', nor 'start', nor 'count', nor 'total'.
• <prop> shall occur 1 or more times under each <query> element.
  • The 'name' attribute shall be present. It shall bear any property name, either as full URL (at least one colon ':' character included) or as property without namespace (no colon ':' character included), in which case the default namespace http://myurc.org/ns/res# shall be assumed.
  • The 'val' attribute shall be present. It shall bear any string indicating a desired value for the pertaining property.
  • The 'wgt' attribute may be present. If present, it shall bear any floating point number between 0.0 and 1.0, indicating the weight of the property-value pair for match finding. A weight of 1.0 indicates that the requested resources must have the given property-value pair (i.e. resources with a different value for the property shall not be included in the response). A weight of 0.0 indicates that the given property-value pair is not relevant for the resource search. The exact meaning of weights between 0.0 and 1.0 is implementation-specific.
• Multiple <prop> elements may have the same 'name' content, thus indicating multiple allowed values for one property.
• A <prop> element may contain any number of <descriptor> elements.
• A <descriptor> element shall have a 'name' and a 'val' attribute.
  • The 'name' attribute shall bear a descriptor name that applies to the nesting property name.
  • A 'val' attribute shall bear any string indicating a desired value for the pertaining descriptor.
• Multiple <descriptor> elements may have the same 'name' content, thus indicating multiple allowed values for one descriptor.

Note: Entity and character references shall be used for reserved characters, when contained in a property name or value (see [XML 1.0], sections 4.1 and 4.6). For example, "&lt;" should be used for "<", "&gt;" should be used for ">", "&amp;" should be used for "&", and "&quot;" should be used for a double quote character (").

4.3. Resource Query: Response

The resource server shall respond to a resource query (HTTP GET or HTTP(S) POST) as follows.

If successful (i.e. the resource server has found at least one resource that matches the request), the resource server shall respond with an HTTP status code of 200, and a list of resources as an XML-encoded body in the format below. Otherwise the resource server shall respond with the appropriate HTTP status code (see below) and an empty body.

<responses>
  <response ref="referenceId" start="firstindex" count="number" total="totalnumber">
    <resource about="aboutURI1" index="index">
      <globalAt>globalURI1</globalAt>
      <prop name="prop11" val="value11">    
        <descriptor name="desc111" val="dvalue111" />
        <descriptor name="desc112" val="dvalue112" />
      </prop>
      <prop name="prop12" val="value12" />
    </resource>
    <resource about="aboutURI2" index="index">
      <globalAt>globalURI2</globalAt>
      <prop name="prop21" val="value21" />
      <prop name="prop22" val="value22" />
    </resource>
  </response>
  <response ref="referenceId" start="firstindex" count="number" total="totalnumber">
    <resource about="aboutURI1" index="index">
      <globalAt>globalURI1</globalAt>
      <prop name="prop11" val="value11">    
        <descriptor name="desc111" val="dvalue111" />
        <descriptor name="desc112" val="dvalue112" />
      </prop>
      <prop name="prop12" val="value12" />
    </resource>
    <resource about="aboutURI2" index="index">
      <globalAt>globalURI2</globalAt>
      <prop name="prop21" val="value21" />
      <prop name="prop22" val="value22" />
    </resource>
  </response>
  <response ref="referenceId" expired="true" />
</responses>

Whereby:

• The message body shall comply with [XML 1.0]. It should not contain any namespace declaration.
• The encoding shall be UTF-8.
• The header fields shall comply with [RFC 2616].
• The <responses> element shall occur exactly once.
• <response> shall occur at least once under <responses>.
• If a best match was requested (in which case the pertaining <query> element had no 'start' and 'count' attributes), <response> shall have no attributes.
• If a previous request was referenced (by using the 'ref' attribute on <query>) and the referenced query had expired, <response> shall have the following attributes:
  • The 'ref' attribute shall reference the expired request. See section Resource Query: HTTP(S) POST Request.
  • The 'expired' attribute shall have the value "true".
  • Note: A resource server should cache results of previous requests (with an assigned referenceId) for at least 30 minutes (to cater for user-caused idle time).
  • Note: If a referenced request has expired, the client needs to repeat the initial query in a subsequent request to get a new referenceId.
• Otherwise (if no best match was requested, and no expiration of referenced request occurred), the <response> element shall have the following attributes:
  • The 'ref' attribute shall specify a server-generated identifier that the client can use later to refer to the original request. See section Resource Query: HTTP(S) POST Request.
  • A 'start' attribute shall be equal to the 'start' attribute of the HTTP POST request, but only if the matching resources list is not empty.
  • A 'count' attribute shall specify the number of matching resources contained. Note that the resource server may choose to return less resources than requested (even if more resources are available), due to time and bandwidth constraints.
  • A 'total' attribute shall specify the number of matching resources in total.
• <resource> shall occur once or multiple times under each <response> element.
  • An 'about' attribute shall occur, specifying a resource's globally unique identifier (i.e. the value of the property http://myurc.org/ns/res#name [RES Namespace]).
• A <globalAt> element shall occur at least once under <resource>. Each <globalAt> element shall contain a URI that can be used to download the resource. Note that the 'globalAt' URI may include a "query component" [RFC 3986].
• A <prop> element shall occur at least once under <resource>. In general, it shall enumerate all properties that the resource server has stored for the pertaining resource.
• <prop> shall have a 'name' attribute and a 'val' attribute, describing a property-value pair of the resource.
  • The 'name' attribute shall bear any property name, as full URL.
  • The 'val' attribute shall bear any string indicating the value for the property.
• Multiple <prop> elements may have the same name to indicate that the resource has multiple values (potentially with different descriptor values) for a single property.
• <prop> may contain any number of <descriptor> elements. In general, it shall enumerate all descriptors that match the pertaining descriptors in the resource query. The specific matching algorithm is implementation-specific.
• <descriptor> shall have a 'name' and a 'val' attribute.
  • The 'name' attribute shall bear a descriptor name that applies to the nesting property name.
  • A 'val' attribute shall bear any string indicating the value for the descriptor.
• Multiple <descriptor> elements within one <prop> element shall not have the same name. If one property has the same value for different values of a descriptor, this shall be reported as multiple <prop> elements with different descriptor values nested.

Note: Entity and character references shall be used for reserved characters, when contained in a property name or value (see [XML 1.0], sections 4.1 and 4.6). For example, "&lt;" should be used for "<", "&gt;" should be used for ">", "&amp;" should be used for "&", and "&quot;" should be used for a double quote character (").

4.4. Resource Query: Relevant HTTP Status Codes

A response to a resource response shall include one of the following HTTP status codes (cf. [RFC 2616], section 10):

5. Resource Retrieval

A client shall retrieve a resource by its URL, as given as element content of the <globalAt> element in the resource response. If multiple URLs are given for a resource, any of them may be used to retrieve it. Note that a resource's URL may include query and fragment components, and may point to any Web server on the Internet. However, any web server offering resource retrieval shall comply to this section of this specification, even if it does not implement the resource query interface.

The MIME type of the resource, if available, shall be the value of its http://myurc.org/ns/res#mimeType [RES-PROP-VOCAB] property, if specified. If this is not specified on the resource, the resource server may infer an appropriate MIME type in an implementation-specific way, or default to "application/octet-stream".

The resource retrieval shall support the If-Modified-Since field in the request header [RFC 2616], by taking into account the http://purl.org/dc/terms/modified [DCMI Terms] property of a resource, if available.

5.1. Resource Retrieval: HTTP GET Request

Anonymous retrieval shall be available through HTTP GET.

The HTTP GET request header should not contain an "Authorization" header [RFC 2617]. If it contains one, the server shall ignore it.

If authentication is required, the resource server may return error code 301 Moved Permanently [RFC 2616], and redirect to the corresponding URL for authenticated retrieval (HTTPS).

5.2. Resource Retrieval: HTTPS GET Request

Authenticated retrieval shall be available through HTTPS GET.

The request header from the client should contain an "Authorization" header with "Basic", userid and password, as specified in [RFC 2617] for basic authentication. If it contains no "Authorization" header or the "Authorization" header contains data that does not grant access to the requested resource, the resource server shall respond with error code 401 Unauthorized [RFC 2616], and with the following information in the response (challenge):

WWW-Authenticate: Basic realm="Login required"

If, after having sent the error code 401, the client's request header still contains no "Authorization" header or the "Authorization" header contains data that does not grant access to the requested resource, the server may respond again with error code 401 Unauthorized [RFC 2616], or with error code 403 Forbidden [RFC 2616], at its discretion.

6. References

6.1. Normative References

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

[RES-PROP-VOCAB]

URC Consortium: Resource Property Vocabulary. Latest specification available at: http://myurc.org/TR/res-prop-vocab/

[RFC 2616]

IETF RFC 2616, Hypertext Transfer Protocol - HTTP/1.1, June 1999, http://www.ietf.org/rfc/rfc2616.txt

[RFC 2617]

IETF RFC 2617, HTTP Authentication: Basic and Digest Access Authentication, June 1999, http://www.ietf.org/rfc/rfc2617.txt

[RFC 3986]

IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005, http://www.ietf.org/rfc/rfc3986.txt

[UCS]

ISO/IEC 10646:2003, Universal Multiple-Octet Coded Character Set (UCS)

[XML 1.0]

W3C Recommendation: Extensible Markup Language (XML) 1.0 (Third Edition), 04 February 2004, http://www.w3.org/TR/2004/REC-xml-20040204/

6.2. Informative References

[DCMI Terms]

DCMI Metadata Terms, http://dublincore.org/documents/dcmi-terms/

[ISO/IEC 24752-5:2008]

Information Technology - User Interfaces - Universal Remote Console - Part 5: Resource Description. ISO, 2008.

[RES Namespace]

XML namespace for resource description properties, as specified in [ISO/IEC 24752-5:2008].

[RFC 2046]

IETF RFC 2046, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, Nov. 1996, http://www.ietf.org/rfc/rfc2046.txt

[XML Namespaces]

W3C Recommendation: Namespaces in XML, W3C Recommendation 14 January 1999, http://www.w3.org/TR/1999/REC-xml-names-19990114/

[XSD Datatypes]

W3C Recommendation: XML Schema Part 2: Datatypes, W3C Recommendation 02 May 2001, ttp://www.w3.org/TR/2001/REC-xmlschema-2-20010502/