[Search] [pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 08                                    
CoRE Working Group                                             K. Hartke
Internet-Draft                                   Universitaet Bremen TZI
Intended status: Informational                            April 16, 2015
Expires: October 18, 2015


                     CoRE Application Descriptions
                       draft-hartke-core-apps-00

Abstract

   This document defines a template for describing the interface of
   RESTful, hypertext-driven applications in Constrained RESTful
   Environments (CoRE).

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

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

   This Internet-Draft will expire on October 18, 2015.

Copyright Notice

   Copyright (c) 2015 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.





Hartke                  Expires October 18, 2015                [Page 1]


Internet-Draft        CoRE Application Descriptions           April 2015


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Application Descriptions  . . . . . . . . . . . . . . . . . .   3
     2.1.  Communication Protocols and URI Schemes . . . . . . . . .   3
     2.2.  Internet Media Types  . . . . . . . . . . . . . . . . . .   3
     2.3.  Representation Formats  . . . . . . . . . . . . . . . . .   4
     2.4.  Link Relation Types . . . . . . . . . . . . . . . . . . .   4
     2.5.  Well-Known Locations  . . . . . . . . . . . . . . . . . .   5
     2.6.  URI Structures  . . . . . . . . . . . . . . . . . . . . .   5
   3.  Template  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   6.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   6
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

1.  Introduction

   The Constrained Application Protocol (CoAP) [RFC7252] is designed to
   enable applications implementing the REST architectural style [REST]
   in Constrained-Node Networks [RFC7228].

   As CoAP applications are implemented and deployed, it becomes
   increasingly important to be able to describe them in some structured
   way to promote interoperability and reuse.  Previous efforts like
   WADL [WADL] focus on code generation from machine-readable service
   descriptions and are not truly RESTful [DWNWADL].

   REST APIs must be hypertext-driven [RESTAPI].  This means that the
   application interface is a description of the common vocabulary
   between the client and the server, centered around media types and
   link relation types, rather than a list of resources and the
   operations supported on them.

   RESTful applications are often easy to understand, but require some
   design effort.  The reward is long-term stability and evolvability
   ("design for decades").  REST is intended for long-lived network-
   based applications that span multiple organizations.

   This document defines a template for describing the interface of
   RESTful, hypertext-driven applications in Constrained RESTful
   Environments (CoRE).






Hartke                  Expires October 18, 2015                [Page 2]


Internet-Draft        CoRE Application Descriptions           April 2015


2.  Application Descriptions

   In this specification, an application description is a named set of
   reusable, self-descriptive components, and is comprised of:

   o  Communication protocols,

   o  URI schemes,

   o  Internet media types,

   o  link relation types, and

   o  optionally, well-known locations.

   Together, these components provide the specific, in-band instructions
   for interfacing with a given service.

2.1.  Communication Protocols and URI Schemes

   The basics of a hypertext-driven REST API are the communication
   protocol(s) spoken between a client and a server.  Although HTTP
   [RFC7230] is by far the most common communication protocol for REST
   APIs, a REST API should typically not be dependent on a specific
   communication protocol.

   The use of a particular protocol is guided by URI schemes [RFC3986]
   describing the URI references found in links and forms (Section 2.3).
   For example, the COAPS URI scheme identifies resources that are
   accessible over CoAP [RFC7252] using DTLS [RFC6347] for transport
   security.

      IANA maintains a list of registered URI schemes at
      <http://www.iana.org/assignments/uri-schemes>.

2.2.  Internet Media Types

   One of the most important aspect of hypertext-driven communications
   is the concept of media types.  Media types are used to label
   resource representations so that it is known how the representation
   should be interpreted, and how it is encoded.  The core of an
   application description should be one or more hypertext media types.

   Media types consist of a top-level type and a subtype, structured
   into trees [RFC6838].  Optionally, media types can have parameters.
   For example, the media type "text/plain; charset=utf-8" is a subtype
   for generic text under the "text" top-level type in the standards
   tree, and has a parameter "charset" set to "utf-8".



Hartke                  Expires October 18, 2015                [Page 3]


Internet-Draft        CoRE Application Descriptions           April 2015


   Media types can be further refined by structured type name suffixes
   (e.g., "+xml" appended to the base subtype name; see Section 4.2.8 of
   [RFC6838]), or by subtype information embedded in the representations
   themselves (e.g., "xmlns" declarations in XML documents).

   A media type must be determined from in-band information (e.g., from
   the CoAP Content-Format option).  Clients must not assume a structure
   from the application context or other out-of-band information.

      IANA maintains a list of registered Internet media types at
      <http://www.iana.org/assignments/media-types>.

      IANA maintains a list of registered structured suffixes at
      <http://www.iana.org/assignments/media-type-structured-suffix>.

      IANA maintains a list of registered CoAP content formats at
      <http://www.iana.org/assignments/core-parameters>.

2.3.  Representation Formats

   In RESTful applications, clients and servers exchange representations
   that capture the current or intended state of a resource and are
   labeled with a media type.  A representation is a sequence of bytes
   whose structure and semantics are specified by a representation
   format, a set of rules for encoding information in digital form.

   Representation formats enable hypertext-driven applications when they
   support the expression of links and/or forms.

   o  A link is a typed connection between two resources [RFC5988] and
      is the primary means for a client to change application state.  It
      is comprised of a context (usually the current resource), a link
      relation type (Section 2.4), a target resource URI, and,
      optionally, some attributes that describe the link target.  URI
      Templates [RFC6570] provide a way to describe a range of URIs as
      the link target through variable expansion.

   o  A form is associated with a single resource and is the primary
      means for a client to change resource state.  It is comprised of a
      target resource URI, a submission method (PUT, POST, PATCH, or
      DELETE), and, optionally, a description of a representation that
      the service accepts as part of the form submission.

2.4.  Link Relation Types

   A link relation type identifies the semantics of a link [RFC5988].
   For example, a link with the relation type "copyright" indicates that




Hartke                  Expires October 18, 2015                [Page 4]


Internet-Draft        CoRE Application Descriptions           April 2015


   the resource identified by the target URI is a statement of the
   copyright terms applying to the current context.

   Relation types are not to be confused with media types [RFC6838];
   they do not identify the format of the representation that results
   when the link is dereferenced.  Rather, they only describe how the
   current context is related to another resource.

      IANA maintains a list of registered link relation types at
      <http://www.iana.org/assignments/link-relations>.

2.5.  Well-Known Locations

   Some applications may require the discovery of information about a
   host ("site-wide metadata").  For example, [RFC6415] defines a
   metadata document format for describing hosts; similarly, [RFC6690]
   defines a link format for the discovery of resources hosted by a
   server.

   Applications that need to define a resource for site-wide metadata
   can register new "well-known locations".  [RFC5785] defines a path
   prefix in HTTP(S) URIs for this purpose, "/.well-known/"; [RFC7252]
   extends this concept to COAP(S) URIs.

      IANA maintains a list of registered well-known URIs at
      <http://www.iana.org/assignments/well-known-uris>.

2.6.  URI Structures

   Application descriptions must not constrain URI structures in ways
   that aren't explicitly allowed by [RFC3986].  In particular,
   mandating particular forms of URI substructure is inappropriate.
   [RFC7320] describes this problematic practice and provides some
   acceptable alternatives for use in application descriptions.

3.  Template

   Application name:

   Protocols:

   URI schemes:

   Media types:

   Link relations:

   Well-known locations:



Hartke                  Expires October 18, 2015                [Page 5]


Internet-Draft        CoRE Application Descriptions           April 2015


4.  Security Considerations

   This document raises no new security issues beyond those described in
   the referenced documents.

5.  IANA Considerations

   This document includes no request to IANA.

6.  Acknowledgements

   Thanks to Carsten Bormann, Stefanie Gerdes, Matthias Kovatsch, Teemu
   Savolainen, and Bilhanan Silverajan for helpful comments and
   discussions that have shaped the document.

   Some of the text in this document has been borrowed from [RESTAPI],
   [RFC5988], and [RFC7320].  All errors are my own.

   This work was funded in part by Nokia.

7.  References

7.1.  Normative References

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, January 2005.

   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
              Uniform Resource Identifiers (URIs)", RFC 5785, April
              2010.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.

   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
              and D. Orchard, "URI Template", RFC 6570, March 2012.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13, RFC
              6838, January 2013.

   [RFC7320]  Nottingham, M., "URI Design and Ownership", BCP 190, RFC
              7320, July 2014.








Hartke                  Expires October 18, 2015                [Page 6]


Internet-Draft        CoRE Application Descriptions           April 2015


7.2.  Informative References

   [DWNWADL]  Gregorio, J., "Do we need WADL?", June 2007,
              <http://bitworking.org/news/193/Do-we-need-WADL>.

   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", Ph.D. Dissertation,
              University of California, Irvine, 2000,
              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
              fielding_dissertation.pdf>.

   [RESTAPI]  Fielding, R., "REST APIs must be hypertext-driven",
              October 2008, <http://roy.gbiv.com/untangled/2008/
              rest-apis-must-be-hypertext-driven>.

   [RFC6347]  Rescorla, E. and N. Modadugu, "Datagram Transport Layer
              Security Version 1.2", RFC 6347, January 2012.

   [RFC6415]  Hammer-Lahav, E. and B. Cook, "Web Host Metadata", RFC
              6415, October 2011.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, August 2012.

   [RFC7228]  Bormann, C., Ersue, M., and A. Keranen, "Terminology for
              Constrained-Node Networks", RFC 7228, May 2014.

   [RFC7230]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Message Syntax and Routing", RFC 7230, June
              2014.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252, June 2014.

   [WADL]     Hadley, M., "Web Application Description Language", W3C
              Member Submission SUBM-wadl-200908316, August 2009,
              <http://www.w3.org/Submission/2009/SUBM-wadl-20090831>.

Author's Address

   Klaus Hartke
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63905
   EMail: hartke@tzi.org



Hartke                  Expires October 18, 2015                [Page 7]