idnits 2.17.1
draft-schuetze-json-hc-03.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document seems to lack the recommended RFC 2119 boilerplate, even if
it appears to use RFC 2119 keywords -- however, there's a paragraph with
a matching beginning. Boilerplate error?
(The document does seem to have the reference to RFC 2119 which the
ID-Checklist requires).
-- The document date (November 30, 2016) is 2702 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Obsolete informational reference (is this intentional?): RFC 2818
(Obsoleted by RFC 9110)
-- Obsolete informational reference (is this intentional?): RFC 5988
(Obsoleted by RFC 8288)
-- Obsolete informational reference (is this intentional?): RFC 7159
(Obsoleted by RFC 8259)
-- Obsolete informational reference (is this intentional?): RFC 7231
(Obsoleted by RFC 9110)
Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 5 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group J. Schuetze
3 Internet-Draft November 30, 2016
4 Intended status: Informational
5 Expires: June 3, 2017
7 JSON-HC
8 draft-schuetze-json-hc-03
10 Abstract
12 This document proposes a media type for representing JSON resources
13 and relations with hypermedia controls.
15 Status of This Memo
17 This Internet-Draft is submitted in full conformance with the
18 provisions of BCP 78 and BCP 79.
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF). Note that other groups may also distribute
22 working documents as Internet-Drafts. The list of current Internet-
23 Drafts is at http://datatracker.ietf.org/drafts/current/.
25 Internet-Drafts are draft documents valid for a maximum of six months
26 and may be updated, replaced, or obsoleted by other documents at any
27 time. It is inappropriate to use Internet-Drafts as reference
28 material or to cite them other than as "work in progress."
30 This Internet-Draft will expire on June 3, 2017.
32 Copyright Notice
34 Copyright (c) 2016 IETF Trust and the persons identified as the
35 document authors. All rights reserved.
37 This document is subject to BCP 78 and the IETF Trust's Legal
38 Provisions Relating to IETF Documents
39 (http://trustee.ietf.org/license-info) in effect on the date of
40 publication of this document. Please review these documents
41 carefully, as they describe your rights and restrictions with respect
42 to this document. Code Components extracted from this document must
43 include Simplified BSD License text as described in Section 4.e of
44 the Trust Legal Provisions and are provided without warranty as
45 described in the Simplified BSD License.
47 Table of Contents
49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
50 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 2
51 3. JSON-HC Documents . . . . . . . . . . . . . . . . . . . . . . 2
52 4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 3
53 5. Hypermedia Controls . . . . . . . . . . . . . . . . . . . . . 3
54 6. Embedded Resource Object . . . . . . . . . . . . . . . . . . 4
55 7. Refresh a Resource Object . . . . . . . . . . . . . . . . . . 4
56 8. Target URL . . . . . . . . . . . . . . . . . . . . . . . . . 4
57 9. Performing Actions . . . . . . . . . . . . . . . . . . . . . 4
58 10. Retrieve available HTTP methods . . . . . . . . . . . . . . . 4
59 11. Profile of a Resource Object . . . . . . . . . . . . . . . . 5
60 12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5
61 13. Security Considerations . . . . . . . . . . . . . . . . . . . 5
62 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6
63 15. Informative References . . . . . . . . . . . . . . . . . . . 6
64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7
66 1. Introduction
68 JSON Hypermedia Controls (JSON-HC) is a standard which establishes
69 conventions for expressing hypermedia controls in JSON [RFC7159].
71 The Hypermedia Controls of JSON-HC provide a way to figure out which
72 Actions are possible with a Resource Object, what is the self URL of
73 the Object and of which profile is the Resource Object.
75 2. Requirements
77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and OPTIONAL" in this
79 document are to be interpreted as described in [RFC2119].
81 3. JSON-HC Documents
83 A JSON-HC Document uses the format described in [RFC7159] and has the
84 media type "application/vnd.hc+json".
86 Its root object MUST be a Resource Object.
88 For example:
90 GET /orders/523 HTTP/1.1
91 Host: example.org
92 Accept: application/vnd.hc+json
94 HTTP/1.1 200 OK
95 Content-Type: application/vnd.hc+json
97 {
98 "self": "/orders/523",
99 "profile": "https://example.org/rels/order",
100 "https://example.org/rels/warehouse": "/warehouse/56",
101 "https://example.org/rels/invoice": "/invoices/873",
102 "currency": "USD",
103 "status": "shipped",
104 "total": 10.20
105 }
107 Here, we have a JSON-HC document representing an order resource with
108 the URI "/orders/523" and the profile as in [RFC6906] defined as
109 ""https://example.org/rels/order"". It has "warehouse" and "invoice"
110 links, and its own state in the form of "currency", "status", and
111 "total" properties.
113 4. Resource Objects
115 A Resource Objects represents a resource.
117 It has no reserved properties.
119 A Resource Object MAY contain Hypermedia Controls with either a
120 Target URL or an Embedded Resource Object as a value.
122 5. Hypermedia Controls
124 Resource Objects MAY contain Hypermedia Controls.
126 A Hypermedia Control is a property name, which is either:
128 o an IANA link relation name
130 o or a valid URI
132 The value of this Hypermedia Control must be an URL to the linked
133 resource or an Embedded Resource Object.
135 If the value is an URL, the Resource Object needs to be fetched
136 ondemand with an additional request.
138 6. Embedded Resource Object
140 If the value of an Hypermedia Control is a JSON object, there is no
141 additional request necessary to fetch the Resource Object for this
142 Hypermedia Control.
144 7. Refresh a Resource Object
146 If the Resource Object has a "self" Hypermedia Control, the value
147 MUST be an URL. A request to the URL will provide the Resource
148 Object.
150 8. Target URL
152 The target URL of an Hypermedia Control is either:
154 o the value of an Hypermedia Control, if it is an URL
156 o the "self" Hypermedia Control of the Embedded Resource Object
158 If the Target URL is not an absolute URL, it must start with a "/"
159 and any request to this Target URL will be preceded with the base
160 path of the initially requested Document.
162 9. Performing Actions
164 The Target URL of an Hypermedia Control can be used as target for
165 HTTP requests.
167 10. Retrieve available HTTP methods
169 JSON-HC does not provide an own way to define, which HTTP methods a
170 JSON-HC Target URL may accept.
172 If a server needs to list the possible HTTP methods available for a
173 resource, it SHOULD provide an Allow Header [RFC7231].
175 OPTIONS /cancelation/123 HTTP/1.1
177 HTTP/1.1 204 No Content
178 Allow: POST, OPTIONS
180 If the resource was requested with an unsupported method, the server
181 should reply with _405 Method not Allowed_ HTTP Status Code.
183 11. Profile of a Resource Object
185 If the Resource Object has a profile Hypermedia Control, a client can
186 use this to figure out of which kind the Resource Object is.
188 12. Examples
190 The following order resource has a self Hypermedia Control as defined
191 by IANA Link Relations and a custom cancel Hypermedia Control.
193 GET /orders/523 HTTP/1.1
194 Host: example.org
195 Accept: application/vnd.hc+json
197 HTTP/1.1 200 OK
198 Content-Type: application/vnd.hc+json
200 {
201 "self": "/orders/523",
202 "profile": "https://example.org/rels/order",
203 "https://example.org/rels/cancel": "/cancelation/873",
204 "currency": "USD",
205 "status": "created",
206 "total": 10.20
207 }
209 If the client wants to cancel the order, it does a POST HTTP Request
210 to the cancel Hypermedia Control.
212 POST /cancelation/123 HTTP/1.1
214 HTTP/1.1 204 No Content
216 If POST would be not available, the server responds with:
218 HTTP/1.1 405 Method Not Allowed
219 Allow: DELETE
221 A client might decide to use DELETE method instead of the hard coded
222 POST method instead.
224 13. Security Considerations
226 Since JSON-HC documents are JSON documents, they inherit all security
227 considerations of RFC 7159 [RFC7159].
229 The linking part of the JSON-HC media type is not known to introduce
230 any new security issues not already discussed in RFC 5988 [RFC5988]
231 for generic use of web linking mechanisms.
233 The JSON-HC documents follow the Web Origin Concept of RFC 6454
234 [RFC6454] and by default only following hypermedia controls to
235 documents of the same origin are allowed. Network resources can also
236 opt into letting other origins read their information, for example,
237 using Cross-Origin Resource Sharing [CORS].
239 14. Privacy Considerations
241 Since JSON-HC documents are JSON documents, they also inherit all
242 privacy considerations of RFC 7159 [RFC7159]. Thus the security
243 goals like defined in RFC 6973 [RFC6973]: Confidentiality, Peer
244 entity authentication, Unauthorized usage and Inappropriate usage
245 need to be handled outside of the JSON-HC documents and are out of
246 scope of this specification.
248 For example JSON Web Tokens [RFC7519] or OAuth 2.0 [RFC6749] can be
249 used alongside of JSON-HC to ensure authentication and deny
250 unauthorized usages and HTTPS [RFC2818] can be used to ensure
251 confidentiality.
253 15. Informative References
255 [CORS] van Kesteren, A., "Cross-Origin Resource Sharing", W3C
256 Working Draft WD-cors-20100727, July 2010,
257 .
259 Latest version available at .
261 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
262 Requirement Levels", BCP 14, RFC 2119,
263 DOI 10.17487/RFC2119, March 1997,
264 .
266 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
267 DOI 10.17487/RFC2818, May 2000,
268 .
270 [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
271 DOI 10.17487/RFC5988, October 2010,
272 .
274 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
275 DOI 10.17487/RFC6454, December 2011,
276 .
278 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
279 RFC 6749, DOI 10.17487/RFC6749, October 2012,
280 .
282 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
283 DOI 10.17487/RFC6906, March 2013,
284 .
286 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J.,
287 Morris, J., Hansen, M., and R. Smith, "Privacy
288 Considerations for Internet Protocols", RFC 6973,
289 DOI 10.17487/RFC6973, July 2013,
290 .
292 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
293 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
294 2014, .
296 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
297 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
298 DOI 10.17487/RFC7231, June 2014,
299 .
301 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
302 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
303 .
305 Author's Address
307 J. Schuetze
309 Email: jans@dracoblue.de