-
-
Save bradgessler/7587671 to your computer and use it in GitHub Desktop.
{ | |
name: "Todo List", | |
items(href: '/lists/1203/items', next_href: "/lists/1203/items?page=2"): [ | |
item(href: '/items/1'): { | |
description: "Pick up pizza", | |
status: "completed" | |
}, | |
item(href: '/items/12'): { | |
description: "Eat pizza", | |
status: "non_started" | |
} | |
] | |
} |
I would limit the key attributes ({key(attributes): value}
) to hrefs that help HON client load and navigate datasets from the service.
{
list(href: '/lists/1'): {
name: "Todo List",
items(href: '/lists/1203/items', next_href: "/lists/1203/items?page=2"): [
item(href: '/items/1'): {
blog_href: "http://example.org/xxxxx",
avatar_href: "http://example.org/yyyyy",
description: "Pick up pizza",
status: "completed"
},
item(href: '/items/12'): {
blog_href: "http://example.org/qqqqqq",
avatar_href: "http://example.org/zzzzzz",
description: "Eat pizza",
status: "non_started"
}
]
}
}
I'm trying to avoid nasty metadata structures that are emerging in JSON hypermedia standards that would make this look like:
{
href: '/lists/1',
name: "Todo List",
items: {
href: '/lists/1203/items',
links: {
next: "/lists/1203/items?page=2"
},
collection: [
{
href: '/items/1',
description: "Pick up pizza",
status: "completed",
blog_href: "http://example.org/xxxxx",
avatar_href: "http://example.org/yyyyy"
},
{
href: '/items/12',
description: "Eat pizza",
status: "non_started",
blog_href: "http://example.org/qqqqqq",
avatar_href: "http://example.org/zzzzzz"
}
]
}
}
When words like "collection" emerge within a data structure like JSON I feel like we're doing it wrong. I've also seen a number of JSON hypermedia standards preface keys with an _
to denote meta data (e.g. _href
) which also feels like an anti-pattern.
Interesting, look what happens when my first example is implemented as Haml XML:
!!! xml
%list{href: '/lists/1'}
%name Todo List
%items{href: '/lists/1203/items'}
%link{rel: "next", href: "/lists/1203/items?page=2"}
%item{href: '/items/1'}
%link{rel: "blog", href: "http://example.org/xxxxx"}
%link{rel: "avatar", href: "http://example.org/yyyyy"}
%description Pick up pizza
%status completed
%item{href: '/items/12'}
%link{rel: "blog", href: "http://example.org/qqqqqq"}
%link{rel: "avatar", href: "http://example.org/zzzzzz"}
%description Eat pizza
%status non_started
I notice a few problems:
- I need to think more about how a hypermedia client would figure out that the
<items/>
attribute contains a collection of<item/>
's - The
%link
elements feel too generic and contrived for this example. They would make more sense if the links were attachments like%link{rel="attachment" href="pizza_receipt.pdf"}
.
Interesting how the development community at large might be blowing up JSON into the complex monstrosity that XML was in the early 2000's.
So, to make sure I have your design in my head correctly, if there are multiple links for a single item (e.g. my home page, my twitter account, my photo album, etc.) you'd make these structural elements in the item body like this:
now, how would i know (when writing the client app) that one of those hrefs should be treated as inline and the other as a navigation?