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, . [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, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . 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, . [Understanding-JSON-Schema] Droettboom, M., "Understanding JSON Schema, Release 1.0", Space Telescope Science Institute , February 2015, . [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, . 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]