Internet DRAFT - draft-lynn-t2trg-model-rest-apis

draft-lynn-t2trg-model-rest-apis







Thing-to-Thing Research Group                                    K. Lynn
Internet-Draft                                                 L. Dornin
Intended status: Informational                              Verizon Labs
Expires: August 25, 2016                               February 22, 2016


              Modeling RESTful APIs with JSON Hyper-Schema
                  draft-lynn-t2trg-model-rest-apis-00

Abstract

   This document explores JSON Hyper-Schema as a method of modeling
   Internet of Things (IoT) systems that follow the principles of the
   Representational State Transfer (REST) architectural style.

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 August 25, 2016.

Copyright Notice

   Copyright (c) 2016 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.





Lynn & Dornin            Expires August 25, 2016                [Page 1]

Internet-Draft            Modeling RESTful APIs            February 2016


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Overview of JSON Schema and Hyper-Schema  . . . . . . . . . .   3
   3.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
   Appendix A.  Future Work  . . . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   The central problem in an IoT domain such as home control might be
   characterized as "translating intention into configuration".  The
   challenge is to translate a high level goal such as "turn off all the
   lights on the first floor", expressed in a natural language, into
   action.  An agent trying to accomplish this goal might look up
   "light" in a semantic registry, discover instances of "light", select
   those instances that fall within a given area, etc., and ultimately
   transmit control packets to devices that match the given criterea.

   A user defining such a goal should not be concerned with the under-
   lying technology, i.e., details of the protocols or data links over
   which the control packets are sent.  Similarly, service providers or
   developers wishing to provide home control solutions would generally
   prefer them to be technology agnostic.  As with other translation
   tasks, this can more easily be accomplished by using one or more
   intermediate abstraction layers.

   Recent research in semantic interoperability in heterogeneous
   environments has underscored the need for semantic alignment at
   various levels [Semantic-Interop].  This document is concerned with
   identifying a fairly primitive abstraction that sufficiently models
   target state and behavior without overly specifying the details of
   the underlying technology.  We proprose to explore REST APIs as a
   reasonable layer at which to abstract devices.

   JSON Hyper-Schema [I-D.luff-json-hyper-schema] is a formalism for
   describing RESTful APIs.  It supports a description of inbound and
   outbound data across the interface, together with link descriptions
   that identify the URIs, link-relations, and methods that apply to
   links.  JSON Hyper-Schema therefore supports the principal of
   Hypertext as the Engine of Application State.  It may also serve as
   input to documentation and code generation tools.






Lynn & Dornin            Expires August 25, 2016                [Page 2]

Internet-Draft            Modeling RESTful APIs            February 2016


2.  Overview of JSON Schema and Hyper-Schema

   JSON Schema is a JSON based format for defining the structure of JSON
   data [RFC7159][I-D.zyp-json-schema].  JSON Hyper-Schema adds
   hyperlink- and hyper-media related keywords to JSON Schema.  This
   section simply lists features of JSON Schema and Hyper-Schema used in
   the examples.  For a detailed overview, see
   [Understanding-JSON-Schema]

2.1.  JSON Schema

   JSON Schema supports:

   -  JSON data types: object, array, number, string, boolean, null

   -  $schema keyword: value identifies meta-schema and version

   -  Definitions and JSON references promote fragment reuse

   -  Schema composition keywords: oneOf, anyOf, allOf

   -  Patterns, regular expressions, more...

2.2.  JSON Hyper-Schema

   JSON Hyper-Schema adds Link Description Objects which include:

   -  href: URI template

   -  rel: link relation

   -  title: a title for the link

   -  targetSchema: JSON Schema describing the link target

   -  mediaType: media type describing the link target

   -  method: REST method that applies to this link

   -  encType: media type of the request

   -  schema: Schema describing the data sent with the request

3.  Examples

   The following examples may be validated at http://json-schema-
   validator.herokuapp.com/.  The first example may be converted to
   markdown using the prmd tool at https://github.com/interagent/prmd.



Lynn & Dornin            Expires August 25, 2016                [Page 3]

Internet-Draft            Modeling RESTful APIs            February 2016


3.1.  Binary Switch Hyper-Schema

   This JSON Hyper-Schema models a generic device on/off capability.

 {
   "$schema": "http://json-schema.org/draft-04/hyper-schema#",
   "id": "http://example.com/schemata/switch-binary#",
   "description": "A simple API for a device that supports on/off.",
   "type": [
     "object"
   ],
   "definitions": {
     "uuid": {
       "description": "Unique identifier of the device",
       "example": "01234567-89ab-cdef-0123-456789abcdef",
       "format": "uuid",
       "readOnly": true,
       "type": [
         "string"
       ]
     },
     "identity": {
       "anyOf": [
         {
           "$ref": "#/definitions/uuid"
         }
       ]
     },
     "invalidated": {
       "description": "Time resource was invalidated",
       "example": "2015-01-01T12:00:00Z",
       "format": "date-time",
       "readOnly": true,
       "type": [
         "string"
       ]
     },
     "updated": {
       "description": "Time resource was last updated",
       "example": "2015-01-01T12:00:01Z",
       "format": "date-time",
       "readOnly": true,
       "type": [
         "string"
       ]
     },
     "SwBinary": {
       "title": "Binary Switch",



Lynn & Dornin            Expires August 25, 2016                [Page 4]

Internet-Draft            Modeling RESTful APIs            February 2016


       "description": "Used to control devices with On/Off capability.",
       "stability": "prototype",
       "type": [
         "object"
       ],
       "definitions": {
         "SetValue": {
           "description": "0..99 (level) or 255 (on)",
           "example": 50,
           "type": "number",
           "multipleOf": 1,
           "oneOf": [
             {
               "minimum": 0,
               "maximum": 99
             },
             {
               "enum": [
                 255
               ]
             }
           ]
         },
         "GetValue": {
           "description": "0 (off) or 255 (on)",
           "example": 255,
           "type": "number",
           "multipleOf": 1,
           "oneOf": [
             {
               "enum": [
                 0,
                 255
               ]
             }
           ]
         }
       },
       "properties": {
         "invalidated": {
           "$ref": "#/definitions/invalidated"
         },
         "updated": {
           "$ref": "#/definitions/updated"
         },
         "Value": {
           "$ref": "#/definitions/SwBinary/definitions/GetValue"
         }



Lynn & Dornin            Expires August 25, 2016                [Page 5]

Internet-Draft            Modeling RESTful APIs            February 2016


       },
       "links": [
         {
           "title": "Set",
           "description": "Update a specific Binary Switch instance.",
           "href": "/id/{(%23%2Fdefinitions%2Fidentity)}/SwBinary/Set",
           "method": "POST",
           "rel": "update",
           "schema": {
             "type": [
               "object"
             ],
             "properties": {
               "Value": {
                 "$ref": "#/definitions/SwBinary/definitions/SetValue"
               }
             },
             "required": [
               "Value"
             ],
             "strictProperties": true
           }
         },
         {
           "title": "Get",
           "description": "Read a specific Binary Switch instance.",
           "href": "/id/{(%23%2Fdefinitions%2Fidentity)}/SwBinary/Get",
           "method": "GET",
           "rel": "self",
           "targetSchema": {
             "$ref": "#/definitions/SwBinary"
           }
         }
       ]
     }
   },
   "properties": {
     "SwBinary": {
       "$ref": "#/definitions/SwBinary"
     }
   },
   "additionalProperties": false,
   "links": [
     {
       "href": "https:/",
       "rel": "self"
     },
     {



Lynn & Dornin            Expires August 25, 2016                [Page 6]

Internet-Draft            Modeling RESTful APIs            February 2016


       "href": "/dev-schema",
       "method": "GET",
       "rel": "self",
       "targetSchema": {
         "additionalProperties": true
       }
     }
   ]
 }

3.2.  JSON Link-Format Document

   With the addition of the required "rel" property to each Link
   Description Object, the link-format example from section 2.4 of
   [I-D.ietf-core-links-json] becomes a valid JSON Hyper-Schema
   document.

   [
     {
       "href": "/sensors",
       "ct": "40",
       "title": "SensorIndex",
       "rel": "self"
     },
     {
       "href": "/sensors/temp",
       "rt": "temperature-c",
       "if": "sensor",
       "rel": "self"
     },
     {
       "href": "/sensors/light",
       "rt": "light-lux",
       "if": "sensor",
       "rel": "self"
     },
     {
       "href": "http://www.example.com/sensors/t123",
       "anchor": "/sensors/temp",
       "rel": "describedby"
     },
     {
       "href": "/t",
       "anchor": "/sensors/temp",
       "rel": "alternate"
     }
   ]




Lynn & Dornin            Expires August 25, 2016                [Page 7]

Internet-Draft            Modeling RESTful APIs            February 2016


4.  IANA Considerations

   This document makes no request of IANA.

   Note to RFC Editor: this section may be removed upon publication as
   an RFC.

5.  Security Considerations

   This document doesn't define new functionality and therefore doesn't
   introduce new security concerns.  However, security considerations
   from related specifications apply:

   o  JSON security: section 12 of [RFC7159]

6.  References

6.1.  Normative References

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <http://www.rfc-editor.org/info/rfc7159>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <http://www.rfc-editor.org/info/rfc7231>.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <http://www.rfc-editor.org/info/rfc7252>.

6.2.  Informative References

   [I-D.luff-json-hyper-schema]
              Luff, G., Zyp, K., and G. Court, "JSON Hyper-Schema:
              Hypertext definitions for JSON Schema", draft-luff-json-
              hyper-schema-00 (work in progress), January 2013.

   [I-D.zyp-json-schema]
              Galiegue, F., Zyp, K., and G. Court, "JSON Schema: core
              definitions and terminology", draft-zyp-json-schema-04
              (work in progress), January 2013.







Lynn & Dornin            Expires August 25, 2016                [Page 8]

Internet-Draft            Modeling RESTful APIs            February 2016


   [I-D.ietf-core-links-json]
              Li, K., Rahman, A., and C. Bormann, "Representing CoRE
              Formats in JSON and CBOR", draft-ietf-core-links-json-04
              (work in progress), November 2015.

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

   [Understanding-JSON-Schema]
              Droettboom, M., "Understanding JSON Schema, Release 1.0",
              Space Telescope Science Institute , February 2015,
              <http://spacetelescope.github.io/
              understanding-json-schema/>.

   [Semantic-Interop]
              Konstantinos, K. and A. Katasonov, "Semantic
              Interoperability on the Web of Things: The Smart Gateway
              Framework", VTT Technical Research Center Tampere,
              Finland, DOI 10.1109/CISIS.2012.200, 2012,
              <https://www.researchgate.net/publication/231203029_Semant
              ic_Interoperability_on_the_Web_of_Things_The_Smart_Gateway
              _Framework>.

Appendix A.  Future Work

   o  Provide more examples.

   o  Discuss relationship to higher semantic layer(s).

Authors' Addresses

   Kerry Lynn
   Verizon Labs
   50-60 Sylvan Rd
   Waltham , MA   02451
   USA

   Phone: +1 781 296 9722
   Email: kerlyn@ieee.org









Lynn & Dornin            Expires August 25, 2016                [Page 9]

Internet-Draft            Modeling RESTful APIs            February 2016


   Laird Dornin
   Verizon Labs
   50-60 Sylvan Rd
   Waltham , MA   02451
   USA

   Phone: +1 781 466 2062
   Email: laird.dornin@verizon.com











































Lynn & Dornin            Expires August 25, 2016               [Page 10]