Representational State Transfer Translation Actions (RESTTA)
draft-szewczyk-restta-02

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on September 20, 2008.

Abstract

The purpose of RESTTA is to help make consistent APIs for representational state transfer (REST) protocols where the REST requests are made through URIs that are in varying formats. This is done first by agreeing on a common set of named resources and named inputs. Applications then provide RESTTA documents that other independent applications can use to translate a named resource into a full URI that can be used to retrieve the resource.

Table of Contents

1.  Introduction
    1.1.  Requirements Language
2.  Terminology
3.  Full Example
4.  RESTTA files
5.  RESTTA delegation
6.  Elements
    6.1.  restta Element
    6.2.  appClass Element sub-element of restta Element
    6.3.  pathPrefix Element sub-element of restta, appClass, and resource
    6.4.  resource Element sub-element of appClass Element
    6.5.  uriPattern Element sub-element of resource Element
    6.6.  input Element sub-element of resource Element
    6.7.  patternItem Element sub-element of input Element
    6.8.  defaultVal Element sub-element of input Element
    6.9.  queryKey Element sub-element of input Element
7.  No IANA Considerations
8.  Security Considerations
9.  References
    9.1.  Normative References
    9.2.  Informative References
§  Author's Address
§  Intellectual Property and Copyright Statements

1.  Introduction

REST (Fielding, R., “Representational State Transfer (REST),” 2000.) [REST] based services are popular because they utilize the existing HTTP architecture inherent to the Internet. This architecture is well understood and REST provides a flexible method to make resource request through HTTP that output in a standard format, such as XML.

The APIs for retrieving resources are usually tied directly to the application layer. However, distributing such APIs among many different applications presents a challenge. Different application technologies can have limitations to the way URIs can be constructed.

RESTAA is a specified way to format an XML (Bray, T., Paoli, P., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (Second Edition),” Ocober 2000.) [XML] document in such a way that it would allow applications to map named resources to URIs in a simple and flexible manner.

1.1.  Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

2.  Terminology

RESTTA revolves around the following ideas

3.  Full Example

The following is a sample RESTTA XML document:

<?xml version='1.0'?>
<restta version="0.2">
	<appClass name="sample" detail="http://www.app.com/sample">

	<resource name="user_profile">

		<input type="uriPattern" name="user_name">
			<patternItem>user_name</patternItem>
			<defaultVal>anonymous<defaultVal>
		</input>

		<input type="uriPattern" name="domain_name">
			<patternItem>domain</patternItem>
			<defaultVal>sitename.com<defaultVal>
		</input>

		<input type="get/post" name="profile_format">
			<queryKey>format</queryKey>
			<defaultVal>XML</defaultVal>
		</input>

		<uriPattern>
			http://[domain]/index.php/[user_name].
		</uriPattern>
	</resource>

	<resource name="rss_feed">
		<uriPattern>/path/to/rss/feed.xml.</uriPattern>
	</resource>

	</appClass>
</restta>

The example XML markup describes an application class "sample" with two resources. The first resource is named "user_profile", and its URI is defined as a pattern. The first resource can take three inputs, two of which must be present in the URI pattern. The other input can either be formatted in a GET query string or as a POST query, as described in [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.). Given the inputs as well as the URI pattern, an application can easily form a final URI to retrieve the resource.

The second resource is defined simply by the URI pattern. In this case it lacks a host name and must be interpreted as a path reletive to the RESTTA file.

4.  RESTTA files

The RESTTA XML file must have the filename "restta.xml" and it must be located inside the root of a provided URI. For example, given "http://domain.com", the RESTTA file would be found in "http://domain.com/restta.xml".

5.  RESTTA delegation

RESTTA application classes may be delegated to other sources by utilizing the RESTTA application class.

The following is a sample RESTTA delegation:

<?xml version='1.0'?>
<restta version="0.2">
	<appClass name="restta" detail="http://peopletab.com/draft-szewczyk-restta-01.html">
	<resource name="restta_delegate">
		<input name="app_class" type="uriPattern" >
			<patternItem>app_class</patternItem>
			<defaultVal>all<defaultVal>
		</input>
		<uriPattern>
			/[app_class]/restta.xml
		</uriPattern>
	<resource>
	</appClass>
</restta>

6.  Elements

This section outlines all the elements, or tags, as well as each element's respective properties. Some tags and properties are required, some are not. As a matter of convention, tags should be in camel case, and property values should avoid reserved characters, as well as characters that would be percent encoded as described in [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.).

6.1.  restta Element

The restta tag is the base restta tag used to encapsulate the application class elements. It is required.

6.2.  appClass Element sub-element of restta Element

The appClass tag is used to encapsulate defined resources. For each application class there must be a corresponding appClass tag with a unique name and detail-URI combination.

6.3.  pathPrefix Element sub-element of restta, appClass, and resource

The pathPrefix element is used to define a prefix path to be prepended to reletive uriPattern elements. It MUST begin with a '/' character and it MUST NOT end in a '/' character. In case there are multiple pathPrefix elements, the one closest to a given resource element should be used. For example, if there is a pathPrefix element as a child of the appClass element, and another under a resource element, the one that is the one under the resource element should override the higher one.

The tag has no defined properties.

6.4.  resource Element sub-element of appClass Element

The resource tag is used to encapsulate a defined URI pattern as well as the optional inputs that will be used to form the final resource URI.

6.5.  uriPattern Element sub-element of resource Element

The uriPattern tag surrounds a string pattern that corresponds to either and absolute URI or a relative URI. If relative, the final URI will formulated as one relative to the RESTTA document. Also, "named inputs" may be part of the uriPattern value. Named inputs are formatted to be easily parsed and replaced by actual input values, and are in the format "[input_name]", where bracket a bracket characters opens and closes the name. Named inputs must match either a "name" property value of a sibling input element, or of a patternItem override element located as a child of a sibling input element.

The tag has no defined properties.

6.6.  input Element sub-element of resource Element

The input tag is used to to define the input that will go into forming the final resource URI for a named resource. This tag is optional, only to be used when there are variable inputs needed to define the final URI.

6.7.  patternItem Element sub-element of input Element

The patternItem tag specifies which named part of the uriPattern the input should be placed into. It is not a required element, its use depends on whether a named part exists in the uriPattern. It must only be used inside an input element that is of the type "uriPattern". If this element is missing, the named part is implied to be the name property value of the input element.

The tag has no defined properties.

6.8.  defaultVal Element sub-element of input Element

The defaultVal tag specifies a default value to go into the final URI request if the application interpreting the document lacks an input value.

The tag has no defined properties.

6.9.  queryKey Element sub-element of input Element

The queryKey tag specifies a key when the parent input is of type "post", "get", or "post/get". This tag is optional. If this element is missing, the query key value is implied to be the name property value of the input element.

The tag has no defined properties.

7.  No IANA Considerations

8.  Security Considerations

Because the retrieval of the RESTTA file relies on DNS (Mockapetris, P., “Domain names - implementation and specification,” November 1987.) [RFC1035], it may be susceptible to poisoning attacks. It is recommended to disregard all final URIs generated from a RESTTA document that point to a different domain if security is of vital concern.

9.  References

9.1. Normative References

9.2. Informative References

Author's Address

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.