Re: [designinghypermediaapis] Re: Enhancing W3Clove example
- Steve Klabnik
- 2012-03-12 @ 10:19
>> 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
>> 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
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
Also amusing to think about this in the context of Fielding:
> 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!