JSON-HC
draft-schuetze-json-hc-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | J. Schuetze | ||
| Last updated | 2016-08-27 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-schuetze-json-hc-00
Network Working Group J. Schuetze
Internet-Draft August 27, 2016
Intended status: Standards Track
Expires: February 28, 2017
JSON-HC
draft-schuetze-json-hc-00
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 February 28, 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 February 28, 2017 [Page 1]
Internet-Draft JSON-HC August 2016
Table of Contents
1. JSON-HC . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 2
4. JSON-HC Documents . . . . . . . . . . . . . . . . . . . . . . 2
5. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 3
6. Hypermedia Controls . . . . . . . . . . . . . . . . . . . . . 3
7. Embedded Resource Object . . . . . . . . . . . . . . . . . . 4
8. Refresh a Resource Object . . . . . . . . . . . . . . . . . . 4
9. Target URL . . . . . . . . . . . . . . . . . . . . . . . . . 4
10. Performing Actions . . . . . . . . . . . . . . . . . . . . . 4
11. Retrieve available HTTP methods . . . . . . . . . . . . . . . 4
12. Profile of a Resource Object . . . . . . . . . . . . . . . . 5
13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5
14. Informative References . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
1. JSON-HC
2. Introduction
JSON Hypermedia Controls (JSON-HC) is a standard which establishes
conventions for expressing hypermedia controls in JSON [RFC4627].
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.
3. 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].
4. JSON-HC Documents
A JSON-HC Document uses the format described in [RFC4627] and has the
media type "application/hc+json".
Its root object MUST be a Resource Object.
For example:
Schuetze Expires February 28, 2017 [Page 2]
Internet-Draft JSON-HC August 2016
GET /orders/523 HTTP/1.1
Host: example.org
Accept: application/hc+json
HTTP/1.1 200 OK
Content-Type: application/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.
5. 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.
6. 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 February 28, 2017 [Page 3]
Internet-Draft JSON-HC August 2016
7. 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.
8. 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.
9. 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.
10. Performing Actions
The Target URL of an Hypermedia Control can be used as target for
HTTP requests.
11. 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 February 28, 2017 [Page 4]
Internet-Draft JSON-HC August 2016
12. 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.
13. 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/hc+json
HTTP/1.1 200 OK
Content-Type: application/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.
14. Informative References
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627,
DOI 10.17487/RFC4627, July 2006,
<http://www.rfc-editor.org/info/rfc4627>.
Schuetze Expires February 28, 2017 [Page 5]
Internet-Draft JSON-HC August 2016
[RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
DOI 10.17487/RFC6906, March 2013,
<http://www.rfc-editor.org/info/rfc6906>.
[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>.
Author's Address
J. Schuetze
Email: jans@dracoblue.de
Schuetze Expires February 28, 2017 [Page 6]