How to model nested collections with JSON+HAL?

[Patrick Mulder]

Hello,

in my application domain, I have some nested resources that may reference each other. What might the hypermedia type for this use case look like:

I want to get the review of a particular album of a particular band.

How would I model these nested relationships? What's the role of hypermedia type in this example?

Thanks,

Patrick

[Mike Kelly]

It probably doesn't make sense to nest reviews within an album
representation, but may do with the album within a band e.g:

GET /band/231876
200 OK

{
_links: { self: { href: "/band/231876" } },
name: "Stars of the Lid",
_embedded: {
albums: [{
links: {
self: { href: "/album/123876123" },
reviews: { href: "/album/123876123/reviews" }
},
name: "Music for Nitrous Oxide",
year: "1995"
},{
links: {
self: { href: "/album/98798799" },
reviews: { href: "/album/98798799/reviews" }
},
name: "The Ballasted Orchestra",
year: "1997"
}]

[Patrick Mulder]

On Fri, Nov 23, 2012 at 5:55 PM, Mike Kelly <mikeke...@gmail.com> wrote:

It probably doesn't make sense to nest reviews within an album
representation, but may do with the album within a band e.g:

GET /band/231876
200 OK

{
  _links: { self: { href: "/band/231876" } },
  name: "Stars of the Lid",
  _embedded: {
    albums: [{
      links: {
        self: { href: "/album/123876123" },
        reviews: { href: "/album/123876123/reviews" }
      },
      name: "Music for Nitrous Oxide",
      year: "1995"
    },{
      links: {
        self: { href: "/album/98798799" },
        reviews: { href: "/album/98798799/reviews" }
      },
      name: "The Ballasted Orchestra",
      year: "1997"
    }]

  }
}

Hi Mike,

thanks for the example! Interesting...

two more questions:

1.  This is format can be used to browse a collection of bands with their albums. Meaning, the hyper-links must be understood by the user who is browsing the data. I will check about how the link processing can be done (I think rendering as <a href="..."> in a common HTML client, but also as data-json attribute in a <ul> for example ? )

2. What would be the effects of defining one's own Media type, such as JSON+bands ?

Thanks for evt. discussion!

BR,

Patrick

[Mike Kelly]

I'm not sure what you are asking here. This particular use of HAL
means that the representation on its own can be used to 'browse' a
band and their albums, it could also be used to represent a link to a
resource that shows you the reviews for a given album.. or any other
type of related resource that you wanted to include a link to. There
is no limit here, it depends on your application and what kind of
client behaviour you are trying to enable.

> 2. What would be the effects of defining one's own Media type, such as
> JSON+bands ?

Unless it's necessary, I think it's better to stick with a generic
media type like hal+json. If you define your own you should probably
build stuff on top of something like hal+json anyway.. then it's more
likely the existing hal libraries will work with your type.

Cheers,
M

[Patrick Mulder]

> 1.  This format can be used to browse a collection of bands with their

> albums. Meaning, the hyper-links must be understood by the user who is
> browsing the data. I will check about how the link processing can be done (I
> think rendering as <a href="..."> in a common HTML client, but also as
> data-json attribute in a <ul> for example ? )

I'm not sure what you are asking here. This particular use of HAL
means that the representation on its own can be used to 'browse' a
band and their albums, it could also be used to represent a link to a
resource that shows you the reviews for a given album.. 

Hm.. I think I am bit lost about the 'interpretation' of the HAL format.

Taking the context of browsing the bands collection, and my client is behind a web browser for a start, I want to render the response from GET /band/231876 into HTML. As far as I understand, I could do the rendering on the client side (with JS) or with some kind of middleware app that takes JSON and renders HTML. 

Now, my question was: What examples are there/how would I transform "_links" into something that the user can browse? Thanks if you have some pointers or ideas on the interpretation of a HAL resource!

Patrick

[Mike Kelly]

Oh ok, well I hacked up the hal browser[1] as a generic tool for
browsing any API that is using the HAL media type.. maybe that will
give you some inspiration?

I'm not aware of any generic tooling, but do you need it? in hal
browser I simply passed the _links object into a template and
generated the html through that.

[1] https://github.com/mikekelly/hal-browser

Cheers,
M

On Mon, Nov 26, 2012 at 1:11 PM, Patrick Mulder

> --
> You received this message because you are subscribed to the Google Groups
> "API Craft" group.
> To unsubscribe from this group, send email to
> api-craft+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/api-craft?hl=en.
>
>



--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Patrick Mulder]

On Mon, Nov 26, 2012 at 2:14 PM, Mike Kelly <mikeke...@gmail.com> wrote:

Oh ok, well I hacked up the hal browser[1] as a generic tool for
browsing any API that is using the HAL media type.. maybe that will
give you some inspiration?

I'm not aware of any generic tooling, but do you need it? in hal
browser I simply passed the _links object into a template and
generated the html through that.

[1] https://github.com/mikekelly/hal-browser

Cheers,
M

Yes, thanks! Helpful to see the interaction of the different components!

Ok, I'll look into this more in detail asap.

[Ismael]

Hi Mike. I've got a related question, but please tell me if this is off-topic.

My question is about resources that represent a collection of things, eg:

{

  _links: {

    search: {

      href: "/products.json?q={q}&sort={sort}"

    }

  },

  items: [

    {title: "One item", _links:{...}},

    ...

  ]

}

Given that the resource is all about a list of items, would those still count as "embedded" resources? I'm a bit torn here as to keeping them as part of the _embedded node for consistency or a normal "items" attribute which seems more semantically correct.

[Mike Kelly]

Yes, in HAL the correct way to do this is use _embedded and an item(s) relation:

{

_links: {
search: {
href: "/products.json?q={q}&sort={sort}"
}
},

_embedded: {

items: [
{title: "One item", _links:{...}},
...
]
}
}

Out of interest; what is it about that which seems semantically
incorrect to you?

Cheers,
M

[Jeff Galang]

Mike, I'm confused. In your HAL browser, you have users and posts, both a collection of items. Posts use 'embedded' while users does not. Can you explain the difference to me?

Thanks

[Mike Kelly]

you mean in hal talk? they're just different resources that I decided
to represent in different ways

Cheers,
M

> To unsubscribe from this group and stop receiving emails from it, send an

> email to api-craft+...@googlegroups.com.
>
> Visit this group at http://groups.google.com/group/api-craft?hl=en.

> For more options, visit https://groups.google.com/groups/opt_out.

[Jeff Galang]

Ok, so it's really just a matter of preference? 

Nice work, btw.

[Mike Kelly]

Yes, exactly.

Thanks :)

Cheers,
M