Resource Server HTTP Interface 1.0
Abstract
This specification defines the HTTP and HTTPS interface for querying, retrieving, and uploading resources from a URC Resource Server. The Resource Server is a key component of the Universal Remote Console framework defined by ISO/IEC 24752: it stores the user interface socket descriptions, presentation templates, atomic resources, and supplementary metadata that controllers and Universal Control Hubs need in order to construct user interfaces dynamically. The interface specified here lets any HTTP-capable client interact with a Resource Server in an interoperable way, independent of the language or platform used to implement either side.
Status of this Document
This document is an Approved Technical Report of the openURC Alliance, dated 4 March 2014. It supersedes the earlier draft of 26 November 2013 and is itself superseded by the 5 June 2015 revision. Comments on this document were collected through the openURC Technical Committee mailing list during the public review period from January 2014 to February 2014.
1. Requirements
A conforming Resource Server shall expose three operations over HTTP or HTTPS: a query operation that accepts resource property constraints and returns matching resource identifiers, a retrieval operation that returns the bytes of a previously identified resource, and an upload operation that allows authorised clients to add new resources to the server. The server shall support both HTTP and HTTPS for the query and retrieval operations and shall require HTTPS for the upload operation, since uploads imply mutation of the server state and authentication of the uploading party.
The interface shall be backwards compatible with the resource property vocabulary defined in [RES-PROP-VOCAB] and shall use the resource description format defined in [ISO/IEC 24752-5:2008]. Servers may implement extensions to the vocabulary, but shall not make such extensions a precondition for the operations defined here.
2. Resource Server URL
A Resource Server is identified by a base URL of the form https://server.example.org/path/. The base URL terminates in a forward slash and serves as the root of the resource namespace. All operations defined in this specification are addressed relative to the base URL. Implementers may organise the path component freely; clients shall not make assumptions about the internal structure of the server beyond the operations defined here.
3. Resource Properties
A resource is described by a set of properties drawn from the resource property vocabulary [RES-PROP-VOCAB]. Properties include identifying information such as the resource identifier and human-readable label, descriptive metadata such as the natural language and modality of the resource, technical metadata such as the MIME type and the resource version, and relational metadata such as the parent resource identifier and the references to related resources. The full set of properties is defined in the companion vocabulary specification.
4. Resource Query
The query operation takes a set of property constraints and returns the resource identifiers that satisfy them. Constraints may be expressed as exact matches or as range matches over numeric and date-typed properties. The query operation may be invoked through an HTTP GET request, in which case the constraints are encoded in the URL query string, or through an HTTP POST request, in which case the constraints are carried in an XML document in the request body.
The HTTP GET form is appropriate for simple queries that fit within the URL length limits commonly enforced by HTTP infrastructure. The POST form is appropriate for queries with many constraints or for queries whose constraints contain characters that would require extensive URL encoding. Both forms return the same response: an XML document listing the matching resource identifiers and, optionally, the property values that satisfied the constraints.
The relevant HTTP status codes are 200 OK for a successful query, 400 Bad Request for a malformed query, 404 Not Found if the Resource Server URL itself is not recognised, and 500 Internal Server Error for a server-side failure.
5. Resource Retrieval
The retrieval operation takes a resource identifier returned by a previous query and returns the bytes of the resource. The operation is invoked through an HTTP GET request to a URL constructed from the Resource Server base URL and the resource identifier. The response carries the resource bytes with the appropriate Content-Type header derived from the resource's MIME type property.
Caching of retrieved resources is permitted and encouraged. The server should set HTTP cache control headers to indicate the expected lifetime of each resource. Clients should respect these headers and may use conditional GET requests with the If-None-Match and If-Modified-Since headers to revalidate cached resources.
6. Resource Upload
The upload operation allows authorised clients to add new resources to the server. The operation is invoked through an HTTPS POST request to a designated upload endpoint. The request body carries the resource bytes and an accompanying XML document describing the resource properties. Authentication is required for upload and shall be performed using HTTP Basic or Digest authentication as defined in [RFC 2617], or any equivalent mechanism agreed between the server and the client.
A successful upload returns 201 Created with a Location header indicating the URL of the newly created resource. A failed upload returns 400 Bad Request for malformed input, 401 Unauthorized for missing or invalid credentials, 403 Forbidden for authenticated but unauthorised clients, or 500 Internal Server Error for a server-side failure.
7. References
7.1 Normative References
- [RES-PROP-VOCAB] — openURC Alliance, Resource Property Vocabulary 1.0.
- [RFC 2616] — IETF RFC 2616, Hypertext Transfer Protocol — HTTP/1.1, June 1999.
- [RFC 2617] — IETF RFC 2617, HTTP Authentication: Basic and Digest Access Authentication, June 1999.
- [RFC 3986] — IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005.
- [XML 1.0] — W3C Recommendation, Extensible Markup Language (XML) 1.0 (Third Edition), February 2004.
7.2 Informative References
- [ISO/IEC 24752-5:2008] — Information Technology — User Interfaces — Universal Remote Console — Part 5: Resource Description.
- [DCMI Terms] — DCMI Metadata Terms.
- [RFC 2046] — IETF RFC 2046, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, November 1996.
8. Acknowledgments
The editors thank the members of the openURC Technical Committee for their detailed review of this specification, and in particular the members of the Resource Server task group for their contributions to the design of the upload operation. The work on this specification was supported in part by the i2home project funded by the European Commission under the Sixth Framework Programme.