Resource Server HTTP Interface 1.0 (DRAFT)

Draft Technical Report 2013-11-26

This version: http://openurc.org/TR/res-serv-http1.0-20131126/
Latest version: http://openurc.org/TR/res-serv-http1.0/
Previous draft version: http://openurc.org/TR/res-serv-http1.0-20121022/ (changes marked)
Latest approved version: (none)
Editors: Gottfried Zimmermann, Parikshit Thakur

Copyright 2013, openURC Alliance

Abstract

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

Status of this Document

This is a public Draft Technical Report in last call review, developed by the editors, hereby made available for review by openURC members and the public. Based on its procedures, the openURC Technical Committee has opened a last call 5-week review period and asks for comments by Dec. 31, 2013. Comments on this document should be sent to res-serv-http-comments@openurc.org, and will be considered for the further development of this document.

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]

There are no open issues.

Pending Issues / To Dos [to be removed before final release]

There are no pending issues.

Closed Issues [to be removed before final release]

  1. In section 4.3, the index attribute is in the response code, but not explained in the text below. Can we get rid of it?
  2. The meaning of weights between 0 and 1 is not clearly defined (implementation-specific right now).
  3. All properties are implicitly ANDed in a resource query. Should we allow for more complex queries, with AND/OR structure?
  4. 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.

2013-11-26 Gottfried Zimmermann

2013-11-12 Gottfried Zimmermann

2013-10-31 Gottfried Zimmermann

2013-10-15 Gottfried Zimmermann, Parikshit Thakur

2013-10-14 Parikshit Thakur

2013-09-10 TC call

2013-06-05 Gottfried Zimmermann

2013-05-31 Gottfried Zimmermann

2012-10-22 Gottfried Zimmermann: Publication of draft (heart-beat)

2013-11-26 Parikshit Thakur:

2011-04-29 Parikshit Thakur:

2011-02-15 Parikshit Thakur:

2011-02-01 Parikshit Thakur:

2009-04-29 Gottfried Zimmermann:

2008-08-14 Gottfried Zimmermann:


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://openurc.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://openurc.org/ns/res#forTargetInstance" [RES Namespace] is described in the RDF schema file at http://openurc.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, given as a list of query properties (key-value pairs). This is called a "resource query". The resource server should try to find a resource that matches most of the query properties (with resources ranked based on match quality). Match quality and details are implementation-specific.

NOTE: A metric for this could be to count the number of matching properties, but properties could also differ in their internal weights (implementation specific for resource servers). Resource server may use various approaches for generating a ranked list of resource for a query, e.g. rule-based or statistical approaches.

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

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.

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

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.

Here is an HTTP GET Request sample for a URC Light resource in "best match" mode (cf. [RES-PROP-VOCAB] for property names and values):

GET /query?http%3A%2F%2Fopenurc.org%2Fns%2Fres%23urclClass=urcl-label
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23urclMode=extend
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23urclEltRef=http%3A%2F%2Fexample.com%2Fwebsite%23elementId
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23type=http%3A%2F%2Fopenurc.org%2Frestypes%23video
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23subtype=http%3A%2F%2Fopenurc.org%2Frestypes%23signLanguageVideo
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23mimeType=video%2Fmp4
&http%3A%2F%2Fpurl.org%2Fdc%2Felements%2F1.1%2Flanguage=gsg
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23resolution=medium
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23includesAudio=false
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23interpreterName=Peter
&http%3A%2F%2Fopenurc.org%2Fns%2Fres%23interpreterType=avatar HTTP/1.1
HOST: res.openurc.org
User-Agent: Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.94 Safari/537.36

Code Listing: HTTP GET Request sample for a URC Light resource. Note that the GET line has been line-wrapped for readability reasons. The second line is supposed to start with "HOST:". Also, there is a blank line at the end of the message header (ending with the User Agent Field).

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">
    <usercontext>
      <prop name="prop1" val="value1">
      <prop name="prop2" val="value2">
    </usercontext>
    <controllercontext>
      <prop name="prop1" val="value1">
      <prop name="prop2" val="value2">
    </controllercontext>
    <prop name="prop1" val="value1">
      <descriptor name="desc1" val="dvalue1" />
      <descriptor name="desc2" val="dvalue2" />
    </prop>
    <prop name="prop2" val="value2" />
  </query>
  <query ref="referenceId" start="firstindex" count="number" />
</queries>

Whereby:

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 (").

NOTE: Although there is no namespace declaration foreseen inside the HTTP(S) POST Request message, the following XML Schema file can be used for syntax checking during development: http://openurc.org/ns/res-serv-http-queries.

Here is the HTTP POST Request sample for the URC Light resource in "best match" mode (cf. [RES-PROP-VOCAB] for property names and values):

POST /query HTTP/1.1
HOST: res.openurc.org
User-Agent: Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.94 Safari/537.36

<queries>
  <query>
    <prop name="http://openurc.org/ns/res#urclClass" val="urcl-label" />
    <prop name="http://openurc.org/ns/res#urclMode" val="extend" />
    <prop name="http://openurc.org/ns/res#urclEltRef" val="http://example.com/website#elementId" />
    <prop name="http://openurc.org/ns/res#type" val="http://openurc.org/restypes#video" />
    <prop name="http://openurc.org/ns/res#subtype" val="http://openurc.org/restypes#signLanguageVideo" />
    <prop name="http://openurc.org/ns/res#mimeType" val="video/mp4" />
    <prop name="http://purl.org/dc/elements/1.1/language" val="dsl" />
    <prop name="http://openurc.org/ns/res#resolution" val="medium" />
    <prop name="http://openurc.org/ns/res#includesAudio" val="false" />
    <prop name="http://openurc.org/ns/res#interpreterName" val="Peter" />
    <prop name="http://openurc.org/ns/res#interpreterType" val="avatar" />
  </query>
</queries>

Code Listing: HTTP POST Request sample for a URC Light resource. Note that there is a blank line between the User Agent Field and the message body (starting with <queries>).

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">
      <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">
      <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">
      <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">
      <globalAt>globalURI2</globalAt>
      <prop name="prop21" val="value21" />
      <prop name="prop22" val="value22" />
    </resource>
  </response>
  <response ref="referenceId" expired="true" />
</responses>

Whereby:

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 (").

NOTE: Although there is no namespace declaration foreseen inside the Response message, the following XML Schema file can be used for syntax checking during development: http://openurc.org/ns/res-serv-http-responses.

Here is an HTTP Response sample for the previous URC Light resource query in "best match" mode (cf. [RES-PROP-VOCAB] for property names and values):

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: application/xml; charset=utf-8

<responses>
  <response ref="ref0001">
    <resource about="http://hdm-stuttgart.de/cloud4all/onlinebanking/transfer#label1">
      <globalAt>http://res.openurc.org/retrieve?name=http%3A%2F%2Fhdm-stuttgart.de%2Fcloud4all%2Fonlinebanking%2Ftransfer%23label1</globalAt>
      <prop name="http://openurc.org/ns/res#name" val="http://hdm-stuttgart.de/cloud4all/onlinebanking/transfer#label1" />
      <prop name="http://purl.org/dc/terms/modified" val="2013-05-31T21:25:00+02:00" />
      <prop name="http://openurc.org/ns/res#type" val="http://openurc.org/restypes#video" />
      <prop name="http://openurc.org/ns/res#subtype" val="http://openurc.org/restypes#signLanguageVideo" />
      <prop name="http://openurc.org/ns/res#includesAudio" val="false" />
      <prop name="http://openurc.org/ns/res#mimeType" val="video/mp4" />
      <prop name="http://purl.org/dc/elements/1.1/language" val="dsl" />
      <prop name="http://openurc.org/ns/res#filename" val="video1.mp4" />
      <prop name="http://purl.org/dc/elements/1.1/title" val="Gebärdensprachevideo für Überweisung">
        <descriptor name="lang" val="de" />
      </prop>
      <prop name="http://purl.org/dc/elements/1.1/creator" val="Gottfried Zimmermann" />
      <prop name="http://openurc.org/ns/res#creatorUri" val="http://hdm-stuttgart.de/zimmermanng" />
      <prop name="http://openurc.org/ns/res#urclClass" val="urcl-label" />
      <prop name="http://openurc.org/ns/res#urclMode" val="extend" />
      <prop name="http://openurc.org/ns/res#urclEltRef" val="http://example.com/website#elementId" />
      <prop name="http://openurc.org/ns/res#resolution" val="medium" />
      <prop name="http://openurc.org/ns/res#height" val="240" />
      <prop name="http://openurc.org/ns/res#width" val="320" />
      <prop name="http://openurc.org/ns/res#iconResource"
        val="http://res.openurc.org/retrieve?name=http%3A%2F%2Fhdm-stuttgart.de%2Fcloud4all%2Fonlinebanking%2Ftransfer%23video1-icon" />
      <prop name="http://openurc.org/ns/res#interpreterName" val="Peter" />
      <prop name="http://openurc.org/ns/res#interpreterType" val="avatar" />
      <prop name="http://openurc.org/ns/res#interpreterIcon"
        val="http://res.openurc.org/retrieve?name=http%3A%2F%2Fhdm-stuttgart.de%2Fcloud4all%2Favatars%2FPeter%23icon" />
    </resource>
  </response>
  <response ref="ref0002">
    <resource about="http://hdm-stuttgart.de/cloud4all/onlinebanking/transfer#label2">
      ...
    </resource>
  </response>
</responses>

Code Listing: HTTP Response sample for a URC Light resource. Note that there is a blank line between the User Agent Field and the message body (starting with <queries>).

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):

Status Code Description
200 OK The request has succeeded, and the response is conveyed through the message body.
204 No Content There is no match for the query. (No message body.)
400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications. (No message body.)
401 Unauthorized The HTTPS request did not contain basic authorization.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request. (No message body.)
501 Not Implemented The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource. (No message body.)
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response. (No message body.)

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://openurc.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

An HTTP GET request shall be made to http://res-serv-url/retrieve?name=resourceName&modified=datetime whereby

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 request made to https://res-serv-url/retrieve?name=resourceName&modified=datetime whereby

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.

5.3. Resource Retrieval: HTTP(S) POST Request

Anonymous or Authenticated retrieval shall be available through HTTP(S) POST. An HTTP(S) POST request shall be made to http(s)://res-serv-url/retrieve?name=resourceName&modified=datetime (description of query parameters as explained in Resource Retrieval HTTP(S) GET Request), with an XML-encoded message body in the following format

An HTTP(S) POST request shall be made with an XML-encoded message body in the following format:

<retrieve>
    <usercontext>
      <prop name="prop1" val="value1">
      <prop name="prop2" val="value2">
    </usercontext>
    <controllercontext>
      <prop name="prop1" val="value1">
      <prop name="prop2" val="value2">
    </controllercontext>
</retrieve>

Whereby:

6. Resource Upload

Authenticated upload shall be available through HTTPS POST.

6.1. Resource Upload: HTTPS POST Request

TODO:

  1. Define RProp file format (TR/res-prop-file1.0-20131126), maybe need MIME type?
  2. Modify request to use multi-part HTTPS message (with resource and ucf file appended)
  3. Extend upload to include any number of attachments (rprop files and proprietary config files)
  4. Define proprietary access rights file format, Resource Access Rights, RAC, maybe need MIME type?

An HTTPS POST request shall be made to https://res-serv/upload (secure connection), with an XML-encoded message body in the following format:

   <upload>
     <resource>
       <props inherit="boolean" >
         <prop name="http://openurc.org/ns/res#type" val="resourceType"/> 
         <prop name="prop1" val="value1" >
           <descriptor name="desc1" val="dvalue1" />
         </prop>
       </props>
       <resourceData>
         <name>resourceName</name>
         <data>BASE64EncodedResourceData</data>
       </resourceData>
     </resource>
     <resource>
       <resourceData>
         <name>resourceName</name>
         <data>BASE64EncodedResourceData</data>
       </resourceData
     </resource>
   </upload>

Whereby:

6.2. Resource Upload: HTTPS POST Response

Upon an upload operation, the resource server shall respond as follows:

   <uploadresponse>
	<resource status="statusCode" name="resourceName">
		<message>textMessage</message>
	</resource>
   </uploadresponse>

Whereby:

Resource upload statusCode

Description

ResourceCreated The resourceName does not exist yet, and a new resource has been created.
ResourceUpdated The resourceName already exists, and a new version has been created.
InvalidFormat The request has an invalid format.
NoWriteAccess The resourceName does not exist yet, and the user has no right to create a new resource.

UpdateDenied

The resourceName already exists, and the user has no right to create a new version of the existing resource.

InvalidResourceData

The content of a <resourceData> element (BASE64EncodedResourceData) is invalid or too large to be uploaded and stored in the resource server.

NoTypeGiven The property 'http://openurc.org/ns/res#type' was not specified as part of <props>.
CustomError An implementation-specific error occurred. In this case, the <message> element should carry a more specific text as textMessage.

NOTE: Resource servers that support access rights for resources are supposed to assign default access rights to newly created resources (new versions inherit the access rights from the previous version). In addition, they can support additional (proprietary) elements in the resource request to assign specific access rights.

7. References

7.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://openurc.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/

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

8. Acknowledgments

Work on this document has been funded in part by the National Institute on Disability and Rehabilitation Research, US Dept of Education under Grant H133E030012 as part of the Universal Interface and Information Technology Access Rehabilitation Engineering Research Center of the University of Wisconsin -Trace Center. The content of this document does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

Work on this document has been funded in part by the EU 6th Framework Program under grant FP6-033502 (project i2home). The content of this document does not necessarily reflect the views or policies of the European Commission, nor does mention of trade names, commercial products, or organizations imply endorsement by the European Commission.