idnits 2.17.1 draft-kelly-json-hal-00.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 (June 7, 2012) is 4341 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Kelly 3 Internet-Draft Stateless 4 Intended status: Informational June 7, 2012 5 Expires: December 9, 2012 7 JSON Hypertext Application Lanuage 8 draft-kelly-json-hal-00 10 Abstract 12 This document proposes a media type for representing resources with 13 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 This Internet-Draft will expire on December 9, 2012. 32 Copyright Notice 34 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 3. HAL Documents . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . . 4 53 4.1. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 4.2. Embedded Resources . . . . . . . . . . . . . . . . . . . . 5 55 5. Link Objects . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 5.1. href . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 5.2. templated . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 5.3. title . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 5.4. hreflang . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 6. Example Document . . . . . . . . . . . . . . . . . . . . . . . 5 61 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 62 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 63 9. Normative References . . . . . . . . . . . . . . . . . . . . . 7 64 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 7 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 1. Introduction 69 There is an emergence of non-HTML HTTP applications ("Web APIs") 70 which use hyperlinks to direct clients around their resources. 72 The JSON Hypertext Application Language (HAL) is a standard which 73 establishes conventions for expressing hyperlinks with JSON 74 [RFC4627]. 76 HAL is a generic media type with which Web APIs can be developed and 77 exposed as series of links. Clients of these APIs can select links 78 by their link relation type and traverse them in order to progress 79 through the application. 81 HAL's conventions result in a uniform interface for serving and 82 consuming hypertext, enabling the creation of general-purpose 83 libraries that can be re-used on any API utilising HAL. 85 The primary design goals of HAL are generality and simplicity. HAL 86 can be applied to many different domains, and imposes the minimal 87 amount of structure necessary to cover the key hypertext requirements 88 (links and embedded documents). 90 2. Requirements 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 94 document are to be interpreted as described in [RFC2119]. 96 3. HAL Documents 98 A HAL Document uses the format described in [RFC4627] and has the 99 media type "application/hal+json". 101 Its root object MUST be a Resource Object. 103 For example: 105 GET /orders/523 HTTP/1.1 106 Host: example.org 107 Accept: application/hal+json 109 HTTP/1.1 200 OK 110 Content-Type: application/hal+json 112 { 113 "_links": { 114 "self": { "href": "/orders/523" }, 115 "warehouse": { "href": "/warehouse/56" }, 116 "invoice": { "href": "/invoices/873" } 117 }, 118 "currency": "USD", 119 "status": "shipped", 120 "total": 10.20 121 } 123 Here, we have a HAL document representing an order resource with the 124 URI "/orders/523". It has "warehouse" and "invoice" links, and its 125 own state in the form of "currency", "status", and "total" 126 properties. 128 4. Resource Objects 130 A Resource Object represents a resource. 132 It has two reserved properties "_links" and "_embedded", which 133 represent Links and Embedded Resources respectively. 135 All other properties MUST be valid JSON, and represent the current 136 state of the resource. 138 4.1. Links 140 The reserved "_links" property is REQUIRED. 142 It is an object whose names are link relation types (as defined by 143 [RFC5988]) and values are either a Link Object or an array of Link 144 Objects. The subject resource of these links is the Resource Object 145 of which the containing "_links" object is a property. 147 It MUST have a "self" property whose value is a Link Object who's 148 target SHOULD be the URI of the subject resource. 150 4.2. Embedded Resources 152 The reserved "_embedded" property is OPTIONAL 154 It is an object whose names are link relation types (as defined by 155 [RFC5988]) and values are either a Resource Object or an array of 156 Resource Objects. 158 5. Link Objects 160 A Link Object represents a hyperlink. It has the following 161 properties: 163 5.1. href 165 The "href" property is REQUIRED. 167 Its value is either a URI [RFC3986] or a URI Template [RFC6570]. 169 If the value is a URI Template then the Link Object SHOULD have a 170 "templated" attribute whose value is true. 172 5.2. templated 174 The "templated" property is OPTIONAL. 176 Its value is boolean and SHOULD be true when the Link Object's "href" 177 property is a URI Template. 179 5.3. title 181 The "title" property is OPTIONAL. 183 Its value is a string and is intended for labeling the link with a 184 human-readable identifier (as defined by [RFC5988]). 186 5.4. hreflang 188 The "hreflang" property is OPTIONAL. 190 Its value is a string and is intended for indicating the language of 191 the target resource (as defined by [RFC5988]). 193 6. Example Document 195 The following is an example document representing a list of orders 196 GET /orders HTTP/1.1 197 Host: example.org 198 Accept: application/hal+json 200 HTTP/1.1 200 OK 201 Content-Type: application/hal+json 203 { 204 "_links": { 205 "self": { "href": "/orders" }, 206 "next": { "href": "/orders?page=2" }, 207 "find": { "href": "/orders{?id}", "templated": true } 208 }, 209 "_embedded": { 210 "orders": [{ 211 "_links": { 212 "self": { "href": "/orders/123" }, 213 "basket": { "href": "/baskets/98712" }, 214 "customer": { "href": "/customers/7809" } 215 }, 216 "total": 30.00, 217 "currency": "USD", 218 "status": "shipped", 219 },{ 220 "_links": { 221 "self": { "href": "/orders/124" }, 222 "basket": { "href": "/baskets/97213" }, 223 "customer": { "href": "/customers/12369" } 224 }, 225 "total": 20.00, 226 "currency": "USD", 227 "status": "processing" 228 }] 229 }, 230 currentlyProcessing: 14, 231 shippedToday: 20 232 } 234 Here, the order list document provides a "next" link directing to the 235 next page, and a "find" link containing a URI Template which can be 236 expanded with an 'id' variable to go directly to a specific order. 238 It also has two embedded resources, "orders". Each of these has its 239 own links to the associated "basket" and "customer" resources, and 240 properties showing their "total", "currency" and "status". 242 Additionally, the order list resource has its own properties 243 "currentlyProcessing" and "shippedToday". 245 7. Security Considerations 247 TBD 249 8. IANA Considerations 251 TBD 253 9. Normative References 255 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 256 Requirement Levels", BCP 14, RFC 2119, March 1997. 258 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 259 Resource Identifier (URI): Generic Syntax", STD 66, 260 RFC 3986, January 2005. 262 [RFC4627] Crockford, D., "The application/json Media Type for 263 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 265 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 267 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 268 and D. Orchard, "URI Template", RFC 6570, March 2012. 270 Appendix A. Acknowledgements 272 Thanks to Darrel Miller, Mike Amundsen, and everyone in hal-discuss 273 for their suggestions and feedback. 275 The author takes all responsibility for errors and omissions. 277 Author's Address 279 Mike Kelly 280 Stateless 282 Email: mike@stateless.co 283 URI: http://stateless.co/