Example scenario #1: api.rarebeers.com

[wis3guy]

I have attempted to formulate a realistic use case for using hypermedia in an API and posted it here. Right away, i went and documented how HAL could be applied to this scenario.

Through this scenario we attempt to outline various ways in which hypermedia could be added to resources, based on a realistic use-case. At the same time, formatting the envisioned responses based on different formats, will reveal overlap and distinctive features of each specification, guiding us towards the most flexible implementation of DotNetHypermedia.

For nostalgic reasons, i stuck with the beers them. And i don't even like beer ... :)

• @JakeGinnivan Could you please have a look at the scenario i wrote up and make changes where you see fit?
• @JakeGinnivan, @danbarua, @kekekeks Do you agree to the formatted implementation? Any suggestions?
• @andlju, @danbarua, @chrisaswain, @panmanphil, @glennblock, @jchannon, @AlexZeitler, @serialseb We now need people to describe what this would look like in other formats.

[JakeGinnivan]

Scenario looks great. If we need more complexity down the track we can add paging, search and also the style could end up being a embedded data on the beer

As a side note, should we start pull requesting everything and discuss on there? We can push new branches up into the repo so anyone can just push a new commit onto that PR as we discuss things?

[wis3guy]

@JakeGinnivan There is paging in there. Styling is not, not sure how that would work. Do you mean as properties on the objects? Or as f.ex. the self link of a beer, based on headers, returning an image? Did you also look at my application/hal+json implementation here?

With regard to your side note, i think that is a good idea. Sorry i'm a bit of a git n00b, so just pushed to the master without thinking about it.

[JakeGinnivan]

In domain, beer is linked to a style.

In Hal we could embed the style rather than linking to it.

[JakeGinnivan]

Example:

BrewDog has the following beers:
Jackhammer (Style is 'Imperial IPA')
5am Saint (Style is 'Red ale')

etc

[panmanphil]

It seems to me that most people who are skeptics of the hypermedia style are skeptics because the examples focus too little on POST and PUT and DELETE, and how to really do that well, and how links help you there. I also the think the killer application links is the logic for non static links.

So I'd put more emphasis on adding a brewery, beers, date ranges the beers are available and that sort of thing.

On Tue, Nov 25, 2014 at 10:12 AM, Geoffrey Braaf notifications@github.com wrote:

@JakeGinnivan https://github.com/JakeGinnivan There is paging in there. Styling is not, not sure how that would work. Do you mean as properties on the objects? Or as f.ex. the self link of a beer, based on headers, returning an image? Did you also look at my application/hal+json implementation here https://github.com/DotNetHypermedia/DotNetHypermedia/blob/master/Scenarios/scenario1-hal.md ?

With regard to your side note, i think that is a good idea. Sorry i'm a bit of a git n00b, so just pushed to the master without thinking about it.

— Reply to this email directly or view it on GitHub https://github.com/DotNetHypermedia/DotNetHypermedia/issues/8#issuecomment-64424665 .

[JakeGinnivan]

:+1:

[wis3guy]

@panmanphil I tried to do that by allowing the PUT of an item into the shopping basket. At the same time, given we are discussing serialisation essentially, it doesn't really 'show' as i only render serialised responses. How do you reckon we could make it stand out better in the scenario description or the HAL implementation?

[wis3guy]

@JakeGinnivan isn't that essentially the same as having a beer->brewery relationship, except with an additional entity, being the style? If so, do you feel it adds something that is not already there?

[JakeGinnivan]

@wis3guy yeah, relationship in the domain is the same. But was thinking in the representation it would not be linked and embedded instead. In hal an _embedded item.

[wis3guy]

Ok, good point.

On Tuesday, November 25, 2014, Jake Ginnivan notifications@github.com wrote:

@wis3guy https://github.com/wis3guy yeah, relationship in the domain is the same. But was thinking in the representation it would not be linked and embedded instead. In hal a _embedded item.

— Reply to this email directly or view it on GitHub https://github.com/DotNetHypermedia/DotNetHypermedia/issues/8#issuecomment-64430446 .

Ciao, Geoffrey

Geoffrey Braaf | +31655793290 Freelance .NET Software Architect & Passionate Developer | http://wis3guy.net Findsi: find-as-i | http://www.findsi.com

[wis3guy]

@joepeg Thank you for your feedback. Appreciate it.

• You are right, i will remove that embedded brewery. I think this is cause by some sloppy copy+paste work my myself.
• I purposefully did not add a separate link for the "Add to cart" operation as that would result in two links to the same resource, one intended for PUT and one for GET operations. Perhaps this decision was guided by my personal interpretation of the spec, as i felt that would be something to mention in the documentation for the rb:basket link relation.

So are you saying it would be better to have the following (snippet)?

{
    "_links" : {
        "curies" : [{
            "name" : "rb",
            "href" : "https://docs.rarebeers.com/{rel}",
            "templated" : true
        }],
        "self" : { "href" : "/basket"},
        "rd:add-to-cart" : { "href" : "/basket"},
        "rd:beer-in-basket" : [
            { "href" : "/beers/20"},
            { "href" : "/beers/42"}
        ]               
    },
    ...
}

I do not have a real preference to be honest.

[wis3guy]

@joepeg Yes, sorry about that, misread your prior comment. I think you are right in that it should be there, it's a logical next step after all. Will add it right now.