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.

Table of Contents

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

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:

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:

• an IANA link relation name
• 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.

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:

• the value of an Hypermedia Control, if it is an URL
• 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.

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

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

Author's Address