librelist archives

Re: Enhancing W3Clove example

Re: Enhancing W3Clove example by Daniel Dyba
- Re: [designinghypermediaapis] Re: Enhancing W3Clove example by Steve Klabnik

Re: Enhancing W3Clove example

From:: Daniel Dyba
Date:: 2012-03-12 @ 05:48

Looks like the first email was dropped.

Respectfully,

Mieczysław Daniel Dyba
Electrical Engineering Associate II
ITS Network Engineering & Security
Los Angeles Department of Water & Power
LinkedIn: http://www.linkedin.com/in/danieldyba
Github (Social Coding): https://github.com/dyba




2012/3/11 Daniel Dyba <daniel.dyba@gmail.com>

> Hey Steve,
>
> I really liked the example you used with w3clove to explain the process of
> building a hypermedia API. It was simple and taken from a real-world
> problem. All my comments relate to the page at (
> https://secure.designinghypermediaapis.com/nodes/building-the-w3clove-api
> ). Here are a few suggestions:
>
> 1) You may want to include a reference to what you mean by MAY and MUST. I
> imagine you probably were thinking of RFC 2119.
> 2) I got thrown off when you started to use Ruby code in the curl program;
> then I read afterward that said you were not calculating the URL but are
> making a point about following a link. If you had given me the warning
> before presenting the example, I probably would have spent less time
> figuring out what you're trying to do. I usually don't jump to the next
> section of text unless I feel confident I had some basic understanding of
> the example. Also, do you think it's a good idea to use Ruby? I use Ruby
> and understand it; however, what if someone reading your example doesn't
> have familiarity with Ruby? Would that hinder their understanding of the
> example? How is their experience of reading your example going to differ
> from someone who knows Ruby?
> 3) I think your example could be enhanced by wrapping up at the end how
> you would use the two APIs. Then highlight the key difference in the
> responses. You've already mentioned the difference between the hypermedia
> API version and the existing version; however, I ended up going to the
> w3clove website and comparing a typical response with the one you created
> just to see how they differed. I wanted my brain to kick in the pattern
> recognition gears so I could say, "Oh yeah, I see how that's different".
>
> There are also a few minor things I noticed on that page:
>
> 1) The code doesn't wrap inside the boxes
> 2) When I scroll to see the code in Step 5, the table of contents text
> gets overlaid onto the page content
>
> Respectfully,
>
> Mieczysław Daniel Dyba
> Electrical Engineering Associate II
> ITS Network Engineering & Security
> Los Angeles Department of Water & Power
> LinkedIn: http://www.linkedin.com/in/danieldyba
> Github (Social Coding): https://github.com/dyba
>
>
>

Re: [designinghypermediaapis] Re: Enhancing W3Clove example

From:: Steve Klabnik
Date:: 2012-03-12 @ 10:19

Hey Daniel!

>> I really liked the example you used with w3clove to explain the process of
>> building a hypermedia API. It was simple and taken from a real-world
>> problem. All my comments relate to the page at
>> 
(https://secure.designinghypermediaapis.com/nodes/building-the-w3clove-api). Here
>> are a few suggestions:

Awesome, thanks. :D

>> 1) You may want to include a reference to what you mean by MAY and MUST. I
>> imagine you probably were thinking of RFC 2119.

Yes! A future iteration of this article will have a real media type
defined, similar to
https://secure.designinghypermediaapis.com/media-types/tekpub-productions.html

This article came out of private email discussions I had with Jaime,
and so it's in a little bit of a rougher state than the other project
article, "Transmuting Philosophy into Machinery"

>> 2) I got thrown off when you started to use Ruby code in the curl program;
>> then I read afterward that said you were not calculating the URL but are
>> making a point about following a link. If you had given me the warning
>> before presenting the example, I probably would have spent less time
>> figuring out what you're trying to do.

Ahh yes. I should have been more clear about this.

> Also, do you think it's a good idea to use Ruby? I use Ruby and
>> understand it; however, what if someone reading your example doesn't have
>> familiarity with Ruby? Would that hinder their understanding of the example?
>> How is their experience of reading your example going to differ from someone
>> who knows Ruby?

Exactly. You'll notice that everywhere else, I'm short on actual
implementations. That's due to me grappling with this question. I have
a few projects built, but since they're in Ruby, I don't want to
alienate anyone... "Building Hypermedia APIs in HTML5 and Node" used
Node.js for this reason, since every web developer is at least
passingly familiar with Javascript.

Also amusing to think about this in the context of Fielding:
http://www.ics.uci.edu/~fielding/pubs/dissertation/net_arch_styles.htm#sec_3_5_3

> Simplicity is reduced due to the need to manage the evaluation 
environment, but that may be compensated in some cases as a result of 
simplifying the client's static functionality

>> 3) I think your example could be enhanced by wrapping up at the end how
>> you would use the two APIs.

Absolutely. See my earlier concerns about implementation details. Once
I make a decision, this will be added in, for sure.

>> 1) The code doesn't wrap inside the boxes
>> 2) When I scroll to see the code in Step 5, the table of contents text
>> gets overlaid onto the page content

Noted. Better CSS is being worked on.

Thanks so much for this feedback!