idnits 2.17.1
draft-michaud-xml-hal-01.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 :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (February 8, 2017) is 2633 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288)
Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group J. Michaud
3 Internet-Draft February 8, 2017
4 Intended status: Informational
5 Expires: August 12, 2017
7 XML Hypertext Application Language
8 draft-michaud-xml-hal-01
10 Abstract
12 This document proposes a media type for representing resources and
13 their relations with hyperlinks.
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 Copyright Notice
32 Copyright (c) 2017 IETF Trust and the persons identified as the
33 document authors. All rights reserved.
35 This document is subject to BCP 78 and the IETF Trust's Legal
36 Provisions Relating to IETF Documents
37 (http://trustee.ietf.org/license-info) in effect on the date of
38 publication of this document. Please review these documents
39 carefully, as they describe your rights and restrictions with respect
40 to this document. Code Components extracted from this document must
41 include Simplified BSD License text as described in Section 4.e of
42 the Trust Legal Provisions and are provided without warranty as
43 described in the Simplified BSD License.
45 Table of Contents
47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
48 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3
49 3. HAL Documents . . . . . . . . . . . . . . . . . . . . . . . . 3
50 4. Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
51 4.1. Reserved Elements . . . . . . . . . . . . . . . . . . . . 4
52 4.1.1. link . . . . . . . . . . . . . . . . . . . . . . . . . 4
53 4.1.2. resource . . . . . . . . . . . . . . . . . . . . . . . 4
54 5. Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
55 5.1. rel . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
56 5.1. href . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
57 5.2. templated . . . . . . . . . . . . . . . . . . . . . . . . 5
58 5.3. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
59 5.4. deprecation . . . . . . . . . . . . . . . . . . . . . . . 5
60 5.5. name . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
61 5.6. profile . . . . . . . . . . . . . . . . . . . . . . . . . 6
62 5.7. title . . . . . . . . . . . . . . . . . . . . . . . . . . 6
63 5.8. hreflang . . . . . . . . . . . . . . . . . . . . . . . . . 6
64 6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
65 7. Media Type Parameters . . . . . . . . . . . . . . . . . . . . 8
66 7.1. profile . . . . . . . . . . . . . . . . . . . . . . . . . 8
67 8. Recommendations . . . . . . . . . . . . . . . . . . . . . . . 8
68 8.1. Self Link . . . . . . . . . . . . . . . . . . . . . . . . 8
69 8.2. Link relations . . . . . . . . . . . . . . . . . . . . . . 8
70 8.3. Hypertext Cache Pattern . . . . . . . . . . . . . . . . . 8
71 8.4. Namespace and prefix . . . . . . . . . . . . . . . . . . . 9
72 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9
73 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
74 11. Normative References . . . . . . . . . . . . . . . . . . . . 9
75 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
76 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 11
77 B.1. How should a client know the
78 meaning/structure/semantics/type of a . . . . . . . . . . 11
79 B.2. Where can I find libraries for working with HAL? . . . . . 11
80 B.3. Why does HAL have no forms? . . . . . . . . . . . . . . . 11
81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11
83 1. Introduction
85 There is an emergence of non-HTML HTTP applications ("Web APIs")
86 which use hyperlinks to direct clients around their resources.
88 The XML Hypertext Application Language (HAL) is a standard which
89 establishes conventions for expressing hypermedia controls, such as
90 links, with XML [W3C.REC-xml-20081126].
92 HAL is a generic media type with which Web APIs can be developed and
93 exposed as series of links. Clients of these APIs can select links
94 by their link relation type and traverse them in order to progress
95 through the application.
97 HAL's conventions result in a uniform interface for serving and
98 consuming hypermedia, enabling the creation of general-purpose
99 libraries that can be re-used on any API utilizing HAL.
101 The primary design goals of HAL are generality and simplicity. HAL
102 can be applied to many different domains, and imposes the minimal
103 amount of structure necessary to cover the key requirements of a
104 hypermedia Web API.
106 2. Requirements
108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
110 document are to be interpreted as described in [RFC2119].
112 3. HAL Documents
114 A HAL Document uses the format described in [W3C.REC-xml-20081126]
115 and has the media type "application/hal+xml".
117 Its root MUST be a resource element.
119 For example:
121 GET /orders/523 HTTP/1.1
122 Host: example.org
123 Accept: application/hal+xml
125 HTTP/1.1 200 OK
126 Content-Type: application/hal+xml
128
129
130
131 USD
132 shipped
133 10.20
134
136 Here, we have a HAL document representing an order resource with the
137 URI "/orders/523". It has "warehouse" and "invoice" links, and its
138 own state in the form of "currency", "status", and "total" elements.
140 4. Resource
142 The resource element represents a Resource and SHOULD also host the
143 set of attributes that describe a Link (as defined by [RFC5988]). See
144 Section 5. and Section 8.1. for details.
146 It has two reserved elements:
148 (1) "link": a link to another resource.
150 (2) "resource": an embedded resource.
152 Everything else MUST be valid XML and represents the current state of
153 the Resource.
155 4.1. Reserved Elements
157 4.1.1. link
159 The reserved "link" element is OPTIONAL.
161 This element MAY be used to host the set of attributes that describe
162 a Link (as defined by [RFC5988]). See Section 5. for details.
164 4.1.2. resource
166 The reserved "resource" element is OPTIONAL
168 If present, this element MUST observe the same constraints defined
169 for the root resource but MUST additionally host a Link so that
170 embedded resources can more easily be identified when processed.
172 Embedded resources MAY be a full, partial, or inconsistent version of
173 the representation served from the target URI.
175 5. Link
177 A Link is defined as a set of attributes that represent a hyperlink
178 from the containing resource to a URI. The attributes are as follows:
180 5.1. rel
182 The "rel" attribute is REQUIRED.
184 It is an attribute whose relation values are link relation types (as
185 defined by [RFC5988]).
187 5.1. href
189 The "href" attribute is REQUIRED.
191 Its value is either a URI [RFC3986] or a URI Template [RFC6570].
193 If the value is a URI Template then the Link SHOULD have a
194 "templated" attribute whose value is true.
196 5.2. templated
198 The "templated" attribute is OPTIONAL.
200 Its value is boolean (as defined by [W3C.REC-xmlschema-2-20041028])
201 and SHOULD be true when the Link's "href" attribute is a URI
202 Template.
204 Its value SHOULD be considered false if the attribute is absent.
206 5.3. type
208 The "type" attribute is OPTIONAL.
210 Its value is a string used as a hint to indicate the media type
211 expected when dereferencing the target resource.
213 5.4. deprecation
215 The "deprecation" attribute is OPTIONAL.
217 Its presence indicates that the link is to be deprecated (i.e.
218 removed) at a future date. Its value is a URL that SHOULD provide
219 further information about the deprecation.
221 A client SHOULD provide some notification (e.g. by logging a warning
222 message) whenever it traverses over a link that has this attribute.
223 The notification SHOULD include the deprecation attribute's value so
224 that a client maintainer can easily find information about the
225 deprecation.
227 5.5. name
229 The "name" attribute is OPTIONAL.
231 Its value MAY be used as a secondary key for selecting Links which
232 share the same relation type.
234 5.6. profile
236 The "profile" attribute is OPTIONAL.
238 Its value is a string which is a URI that hints about the profile (as
239 defined by [RFC6906]) of the target resource.
241 5.7. title
243 The "title" attribute is OPTIONAL.
245 Its value is a string and is intended for labeling the link with a
246 human-readable identifier (as defined by [RFC5988]).
248 5.8. hreflang
250 The "hreflang" attribute is OPTIONAL.
252 Its value is a string and is intended for indicating the language of
253 the target resource (as defined by [RFC5988]).
255 6. Example
257 The following is an example representing a list of orders
259 GET /orders HTTP/1.1
260 Host: example.org
261 Accept: application/hal+xml
263 HTTP/1.1 200 OK
264 Content-Type: application/hal+xml
266
267
268
269
270
271
272 30.00
273 USD
274 shipped
275
276
277
278
279 20.00
280 USD
281 processing
282
283 14
284 20
285
287 Here, the order list document provides a "next" link directing to the
288 next page, and a "find" link containing a URI Template which can be
289 expanded with an 'id' variable to go directly to a specific order.
291 It also has two embedded resources, "order". Each of these has its
292 own links to the associated "basket" and "customer" resources, and
293 properties showing their "total", "currency" and "status".
295 Additionally, the order list resource has its own properties
296 "currentlyProcessing" and "shippedToday".
298 7. Media Type Parameters
300 7.1. profile
302 The media type identifier application/hal+xml MAY also include an
303 additional "profile" parameter (as defined by [RFC6906])
305 HAL documents that are served with the "profile" parameter still
306 SHOULD include a "profile" link belonging to the root resource.
308 8. Recommendations
310 8.1. Self Link
312 Each Resource SHOULD have a 'self' link that corresponds with the
313 IANA registered 'self' relation (as defined by [RFC5988]) and whose
314 target is the resource's URI.
316 8.2. Link relations
318 Custom link relation types (Extension Relation Types in [RFC5988])
319 SHOULD be URIs that when dereferenced in a web browser provide
320 relevant documentation, in the form of an HTML page, about the
321 meaning and/or behavior of the target Resource. This will improve
322 the discoverability of the API.
324 The CURIE Syntax [W3C.NOTE-curie-20101216] MAY be used for brevity
325 for these URIs. CURIEs are established within a HAL document via XML
326 namespace on the root Resource.
328
329
330
332 The above demonstrates the relation "http://a.com/rels/widgets" being
333 abbreviated to "acme:widgets" via CURIE syntax.
335 8.3. Hypertext Cache Pattern
337 The "hypertext cache pattern" allows servers to use embedded
338 resources to dynamically reduce the number of requests a client
339 makes, improving the efficiency and performance of the application.
341 Clients MAY be automated for this purpose so that, for any given link
342 relation, they will read from an embedded resource (if present) in
343 preference to traversing a link.
345 To activate this client behavior for a given link, servers SHOULD add
346 an embedded resource into the representation with the same relation.
348 Servers SHOULD NOT entirely "swap out" a link for an embedded
349 resource (or vice versa) because client support for this technique is
350 OPTIONAL.
352 The following examples shows the hypertext cache pattern applied to
353 an "author" link:
355 Before:
357
358
359
361 After:
363
364
365
366 Alan Watts
367 January 6, 1915
368 November 16, 1973
369
370
372 8.4. Namespace and prefix
374 The default namespace of "http://stateless.co/hal/ns" SHOULD be used
375 to allow for mixed, and potentially conflicting, xml vocabularies to
376 coexist in the same xml instance (e.g. embedding an
377 application/hal+xml payload in another xml).
379 If a namespace prefix is needed, "hal" MAY be used by default.
381 9. Security Considerations
383 TBD
385 10. IANA Considerations
387 TBD
389 11. Normative References
391 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
392 March 2013.
394 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
395 Requirement Levels", BCP 14, RFC 2119, March 1997.
397 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
398 Resource Identifier (URI): Generic Syntax", STD 66, RFC
399 3986, January 2005.
401 [W3C.REC-xml-20081126]
403 Bray, T., Paoli, J., Sperberg-McQueen, C. M., Maler, E.,
404 Yergeau, F., "Extensible Markup Language (XML) 1.0 (Fifth
405 Edition)", World Wide Web Consortium REC REC-xml-20081126,
406 November 2008, .
409 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
411 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
412 and D. Orchard, "URI Template", RFC 6570, March 2012.
414 [W3C.NOTE-curie-20101216]
416 McCarron, S. and M. Birbeck, "CURIE Syntax 1.0", World
417 Wide Web Consortium NOTE NOTE-curie-20101216, December
418 2010, .
420 [W3C.REC-xmlschema-2-20041028]
422 Biron, P. V., Malhotra, A., "XML Schema Part 2: Datatypes
423 Second Edition", World Wide Web Consortium REC REC-
424 xmlschema-2-20041028, October 2004,
425 .
427 Appendix A. Acknowledgements
429 Thanks to Mike Kelly for making this specification possible through
430 the creation of HAL and the hal+json specification.
432 I would also like to thank folks on the Hal Discuss Google group for
433 providing feedback for the draft.
435 The author takes all responsibility for errors and omissions.
437 Appendix B. Frequently Asked Questions
439 B.1. How should a client know the meaning/structure/semantics/type of a
440 resource?
442 There are two main approaches to solving this problem. Both involve
443 exposing additional documentation describing the resource which may
444 be human and/or machine readable (e.g. an HTML page, an XML Schema,
445 an ALPS profile, etc.). The difference between the two approaches is
446 in where that URI is shared with the client, which is either:
448 (1) The relation documentation associated to a Link relation type.
450 (2) A 'profile' (via a Link's profile attribute or via a Link with a
451 'profile' relation type).
453 B.2. Where can I find libraries for working with HAL?
455 A list of libraries is maintained here:
456 http://stateless.co/hal_specification.html
458 B.3. Why does HAL have no forms?
460 Omitting forms from HAL was an intentional design decision that was
461 made to keep it focused on linking for APIs. HAL is therefore a good
462 candidate for use as a base media type on which to build more complex
463 capabilities.
465 Author's Address
467 Jeff Michaud
469 Email: cometaj2@comcast.net
470 Twitter: @cometaj2