Internet DRAFT - draft-schuetze-json-hc

draft-schuetze-json-hc







Network Working Group                                        J. Schuetze
Internet-Draft                                         November 30, 2016
Intended status: Informational
Expires: June 3, 2017


                                JSON-HC
                       draft-schuetze-json-hc-03

Abstract

   This document proposes a media type for representing JSON resources
   and relations with hypermedia controls.

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 June 3, 2017.

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.






Schuetze                  Expires June 3, 2017                  [Page 1]

Internet-Draft                   JSON-HC                   November 2016


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Requirements  . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  JSON-HC Documents . . . . . . . . . . . . . . . . . . . . . .   2
   4.  Resource Objects  . . . . . . . . . . . . . . . . . . . . . .   3
   5.  Hypermedia Controls . . . . . . . . . . . . . . . . . . . . .   3
   6.  Embedded Resource Object  . . . . . . . . . . . . . . . . . .   4
   7.  Refresh a Resource Object . . . . . . . . . . . . . . . . . .   4
   8.  Target URL  . . . . . . . . . . . . . . . . . . . . . . . . .   4
   9.  Performing Actions  . . . . . . . . . . . . . . . . . . . . .   4
   10. Retrieve available HTTP methods . . . . . . . . . . . . . . .   4
   11. Profile of a Resource Object  . . . . . . . . . . . . . . . .   5
   12. Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   13. Security Considerations . . . . . . . . . . . . . . . . . . .   5
   14. Privacy Considerations  . . . . . . . . . . . . . . . . . . .   6
   15. Informative References  . . . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

1.  Introduction

   JSON Hypermedia Controls (JSON-HC) is a standard which establishes
   conventions for expressing hypermedia controls in JSON [RFC7159].

   The Hypermedia Controls of JSON-HC provide a way to figure out which
   Actions are possible with a Resource Object, what is the self URL of
   the Object and of which profile is the Resource Object.

2.  Requirements

   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 [RFC2119].

3.  JSON-HC Documents

   A JSON-HC Document uses the format described in [RFC7159] and has the
   media type "application/vnd.hc+json".

   Its root object MUST be a Resource Object.

   For example:









Schuetze                  Expires June 3, 2017                  [Page 2]

Internet-Draft                   JSON-HC                   November 2016


         GET /orders/523 HTTP/1.1
         Host: example.org
         Accept: application/vnd.hc+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.hc+json

         {
           "self": "/orders/523",
           "profile": "https://example.org/rels/order",
           "https://example.org/rels/warehouse": "/warehouse/56",
           "https://example.org/rels/invoice": "/invoices/873",
           "currency": "USD",
           "status": "shipped",
           "total": 10.20
         }

   Here, we have a JSON-HC document representing an order resource with
   the URI "/orders/523" and the profile as in [RFC6906] defined as
   ""https://example.org/rels/order"".  It has "warehouse" and "invoice"
   links, and its own state in the form of "currency", "status", and
   "total" properties.

4.  Resource Objects

   A Resource Objects represents a resource.

   It has no reserved properties.

   A Resource Object MAY contain Hypermedia Controls with either a
   Target URL or an Embedded Resource Object as a value.

5.  Hypermedia Controls

   Resource Objects MAY contain Hypermedia Controls.

   A Hypermedia Control is a property name, which is either:

   o  an IANA link relation name

   o  or a valid URI

   The value of this Hypermedia Control must be an URL to the linked
   resource or an Embedded Resource Object.

   If the value is an URL, the Resource Object needs to be fetched
   ondemand with an additional request.




Schuetze                  Expires June 3, 2017                  [Page 3]

Internet-Draft                   JSON-HC                   November 2016


6.  Embedded Resource Object

   If the value of an Hypermedia Control is a JSON object, there is no
   additional request necessary to fetch the Resource Object for this
   Hypermedia Control.

7.  Refresh a Resource Object

   If the Resource Object has a "self" Hypermedia Control, the value
   MUST be an URL.  A request to the URL will provide the Resource
   Object.

8.  Target URL

   The target URL of an Hypermedia Control is either:

   o  the value of an Hypermedia Control, if it is an URL

   o  the "self" Hypermedia Control of the Embedded Resource Object

   If the Target URL is not an absolute URL, it must start with a "/"
   and any request to this Target URL will be preceded with the base
   path of the initially requested Document.

9.  Performing Actions

   The Target URL of an Hypermedia Control can be used as target for
   HTTP requests.

10.  Retrieve available HTTP methods

   JSON-HC does not provide an own way to define, which HTTP methods a
   JSON-HC Target URL may accept.

   If a server needs to list the possible HTTP methods available for a
   resource, it SHOULD provide an Allow Header [RFC7231].

                     OPTIONS /cancelation/123 HTTP/1.1

                     HTTP/1.1 204 No Content
                     Allow: POST, OPTIONS

   If the resource was requested with an unsupported method, the server
   should reply with _405 Method not Allowed_ HTTP Status Code.







Schuetze                  Expires June 3, 2017                  [Page 4]

Internet-Draft                   JSON-HC                   November 2016


11.  Profile of a Resource Object

   If the Resource Object has a profile Hypermedia Control, a client can
   use this to figure out of which kind the Resource Object is.

12.  Examples

   The following order resource has a self Hypermedia Control as defined
   by IANA Link Relations and a custom cancel Hypermedia Control.

         GET /orders/523 HTTP/1.1
         Host: example.org
         Accept: application/vnd.hc+json

         HTTP/1.1 200 OK
         Content-Type: application/vnd.hc+json

         {
           "self": "/orders/523",
           "profile": "https://example.org/rels/order",
           "https://example.org/rels/cancel": "/cancelation/873",
           "currency": "USD",
           "status": "created",
           "total": 10.20
         }

   If the client wants to cancel the order, it does a POST HTTP Request
   to the cancel Hypermedia Control.

                      POST /cancelation/123 HTTP/1.1

                      HTTP/1.1 204 No Content

   If POST would be not available, the server responds with:

                      HTTP/1.1 405 Method Not Allowed
                      Allow: DELETE

   A client might decide to use DELETE method instead of the hard coded
   POST method instead.

13.  Security Considerations

   Since JSON-HC documents are JSON documents, they inherit all security
   considerations of RFC 7159 [RFC7159].






Schuetze                  Expires June 3, 2017                  [Page 5]

Internet-Draft                   JSON-HC                   November 2016


   The linking part of the JSON-HC media type is not known to introduce
   any new security issues not already discussed in RFC 5988 [RFC5988]
   for generic use of web linking mechanisms.

   The JSON-HC documents follow the Web Origin Concept of RFC 6454
   [RFC6454] and by default only following hypermedia controls to
   documents of the same origin are allowed.  Network resources can also
   opt into letting other origins read their information, for example,
   using Cross-Origin Resource Sharing [CORS].

14.  Privacy Considerations

   Since JSON-HC documents are JSON documents, they also inherit all
   privacy considerations of RFC 7159 [RFC7159].  Thus the security
   goals like defined in RFC 6973 [RFC6973]: Confidentiality, Peer
   entity authentication, Unauthorized usage and Inappropriate usage
   need to be handled outside of the JSON-HC documents and are out of
   scope of this specification.

   For example JSON Web Tokens [RFC7519] or OAuth 2.0 [RFC6749] can be
   used alongside of JSON-HC to ensure authentication and deny
   unauthorized usages and HTTPS [RFC2818] can be used to ensure
   confidentiality.

15.  Informative References

   [CORS]     van Kesteren, A., "Cross-Origin Resource Sharing", W3C
              Working Draft WD-cors-20100727, July 2010,
              <http://www.w3.org/TR/2010/WD-cors-20100727/>.

              Latest version available at <http://www.w3.org/TR/cors/>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC2818]  Rescorla, E., "HTTP Over TLS", RFC 2818,
              DOI 10.17487/RFC2818, May 2000,
              <http://www.rfc-editor.org/info/rfc2818>.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988,
              DOI 10.17487/RFC5988, October 2010,
              <http://www.rfc-editor.org/info/rfc5988>.

   [RFC6454]  Barth, A., "The Web Origin Concept", RFC 6454,
              DOI 10.17487/RFC6454, December 2011,
              <http://www.rfc-editor.org/info/rfc6454>.



Schuetze                  Expires June 3, 2017                  [Page 6]

Internet-Draft                   JSON-HC                   November 2016


   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <http://www.rfc-editor.org/info/rfc6749>.

   [RFC6906]  Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
              DOI 10.17487/RFC6906, March 2013,
              <http://www.rfc-editor.org/info/rfc6906>.

   [RFC6973]  Cooper, A., Tschofenig, H., Aboba, B., Peterson, J.,
              Morris, J., Hansen, M., and R. Smith, "Privacy
              Considerations for Internet Protocols", RFC 6973,
              DOI 10.17487/RFC6973, July 2013,
              <http://www.rfc-editor.org/info/rfc6973>.

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

   [RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <http://www.rfc-editor.org/info/rfc7519>.

Author's Address

   J. Schuetze

   Email: jans@dracoblue.de



















Schuetze                  Expires June 3, 2017                  [Page 7]