Permalink
Browse files

05 draft

  • Loading branch information...
mikekelly committed Feb 12, 2013
1 parent 769c9f2 commit edba74ed7c43ef2527c00b3810465c5c6034dea6
Showing with 1,033 additions and 48 deletions.
  1. +48 −48 draft-kelly-json-hal-04.txt
  2. +615 −0 draft-kelly-json-hal-05.txt
  3. +370 −0 draft-kelly-json-hal-05.xml
@@ -4,16 +4,17 @@
Network Working Group M. Kelly
Internet-Draft Stateless
-Intended status: Informational 2012
+Intended status: Informational February 12, 2013
+Expires: August 16, 2013
- JSON Hypermedia API Language
+ JSON Hypertext Application Language
draft-kelly-json-hal-04
Abstract
This document proposes a media type for representing resources and
- their relations as hypermedia.
+ their relations with hyperlinks.
Status of This Memo
@@ -30,9 +31,11 @@ Status of This Memo
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 August 16, 2013.
+
Copyright Notice
- Copyright (c) 2012 IETF Trust and the persons identified as the
+ Copyright (c) 2013 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
@@ -47,17 +50,17 @@ Copyright Notice
Table of Contents
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3. HAL Documents . . . . . . . . . . . . . . . . . . . . . . . . 3
-Kelly Expires [Page 1]
+Kelly Expires August 16, 2013 [Page 1]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 3. HAL Documents . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Reserved Properties . . . . . . . . . . . . . . . . . . . 4
4.1.1. _links . . . . . . . . . . . . . . . . . . . . . . . 4
@@ -66,7 +69,7 @@ Internet-Draft JSON Hypermedia API Language 2012
5.1. href . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.2. templated . . . . . . . . . . . . . . . . . . . . . . . . 5
5.3. type . . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 5.4. type . . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 5.4. deprecation . . . . . . . . . . . . . . . . . . . . . . . 5
5.5. name . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.6. profile . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.7. title . . . . . . . . . . . . . . . . . . . . . . . . . . 6
@@ -94,25 +97,27 @@ Internet-Draft JSON Hypermedia API Language 2012
1. Introduction
There is an emergence of non-HTML HTTP applications ("Web APIs")
- which use hypermedia to direct clients around their resources.
+ which use hyperlinks to direct clients around their resources.
- The JSON Hypermedia API Language (HAL) is a standard which
+ The JSON Hypertext Application Language (HAL) is a standard which
establishes conventions for expressing hypermedia controls, such as
links, with JSON [RFC4627].
- HAL is a generic media type with which Web APIs can be developed and
- exposed as series of links. Clients of these APIs can select links
- by their link relation type and traverse them in order to progress
- through the application.
-Kelly Expires [Page 2]
+
+Kelly Expires August 16, 2013 [Page 2]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
+
+ HAL is a generic media type with which Web APIs can be developed and
+ exposed as series of links. Clients of these APIs can select links
+ by their link relation type and traverse them in order to progress
+ through the application.
HAL's conventions result in a uniform interface for serving and
consuming hypermedia, enabling the creation of general-purpose
@@ -121,7 +126,7 @@ Internet-Draft JSON Hypermedia API Language 2012
The primary design goals of HAL are generality and simplicity. HAL
can be applied to many different domains, and imposes the minimal
amount of structure necessary to cover the key requirements of a
- hypermedia API.
+ hypermedia Web API.
2. Requirements
@@ -157,18 +162,18 @@ Internet-Draft JSON Hypermedia API Language 2012
}
- Here, we have a HAL document representing an order resource with the
- URI "/orders/523". It has "warehouse" and "invoice" links, and its
- own state in the form of "currency", "status", and "total"
- properties.
-
-Kelly Expires [Page 3]
+Kelly Expires August 16, 2013 [Page 3]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
+
+ Here, we have a HAL document representing an order resource with the
+ URI "/orders/523". It has "warehouse" and "invoice" links, and its
+ own state in the form of "currency", "status", and "total"
+ properties.
4. Resource Objects
@@ -205,8 +210,9 @@ Internet-Draft JSON Hypermedia API Language 2012
Emebedded Reources MAY be a full, partial, or inconsistent version of
the representation served from the target URI.
- Clients MAY switch automatically from from traversing a link to
- reading an embedded resources interchangably.
+ Clients MAY switch transparently between links and embedded resources
+ that share the same link relation, however this SHOULD NOT be
+ considered a requirement of this specification.
5. Link Objects
@@ -215,15 +221,9 @@ Internet-Draft JSON Hypermedia API Language 2012
-
-
-
-
-
-
-Kelly Expires [Page 4]
+Kelly Expires August 16, 2013 [Page 4]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
5.1. href
@@ -252,7 +252,7 @@ Internet-Draft JSON Hypermedia API Language 2012
Its value is a string used as a hint to indicate the media type
expected when dereferencing the target resource.
-5.4. type
+5.4. deprecation
The "deprecation" property is OPTIONAL.
@@ -277,9 +277,9 @@ Internet-Draft JSON Hypermedia API Language 2012
-Kelly Expires [Page 5]
+Kelly Expires August 16, 2013 [Page 5]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
5.6. profile
@@ -333,9 +333,9 @@ Internet-Draft JSON Hypermedia API Language 2012
-Kelly Expires [Page 6]
+Kelly Expires August 16, 2013 [Page 6]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
},{
@@ -389,9 +389,9 @@ Internet-Draft JSON Hypermedia API Language 2012
-Kelly Expires [Page 7]
+Kelly Expires August 16, 2013 [Page 7]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
Custom link relation types (Extension Relation Types in [RFC5988])
@@ -445,9 +445,9 @@ Internet-Draft JSON Hypermedia API Language 2012
-Kelly Expires [Page 8]
+Kelly Expires August 16, 2013 [Page 8]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
[RFC4627] Crockford, D., "The application/json Media Type for
@@ -501,9 +501,9 @@ B.3. Why are the reserved properties prefixed with an underscore?
-Kelly Expires [Page 9]
+Kelly Expires August 16, 2013 [Page 9]
-Internet-Draft JSON Hypermedia API Language 2012
+Internet-Draft JSON Hypertext Application Language February 2013
Another reason for prefixing the reserved properties is to make it
@@ -556,4 +556,4 @@ Author's Address
-Kelly Expires [Page 10]
+Kelly Expires August 16, 2013 [Page 10]
Oops, something went wrong.

0 comments on commit edba74e

Please sign in to comment.