Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • I thought you of all people understood REST. :-(

    Presumably, if I had a sufficiently smart client that understood the media types used in the application, I’d point it at the root URI, it’d discover all the URIs, and I could manipulate and fetch data along the way.

    That’s a nice theory, but has very little with how people want to use these APIs.

    That’s not theory. That’s the web. Also, have you heard of something called AtomPub [ietf.org]? That’s like that, too. There are a lot of de

    • I thought you of all people understood REST.

      To be honest, I'd totally missed this part of it. I understand why Roy thinks it's important, but I'm not sure that I think it's important.

      My goals for doing something REST-like are several fold ...

      First, share the same URI space between what a browser sees and what a non-browser would see. This works quite well for everything that should be POST, PUT, and DELETE. For GETs, you end up with a bunch of stuff like /person/1/edit_form because browsers kind of suck, but that's ok.

      Second, by sharing that URI space, I can re-use all my non-GET code. The GET code I can't, because the HTML I deliver to a browser is nothing like what an application client would want, but again, browser sucks, so that's ok.

      I do like the idea of providing actual "media types", although I imagine my media types would mostly be well-defined JSON "blobs". This just makes sense, and should be part of one's spec for an API anyway, since it basically defines input and output parameters.

      However, I'm not convinced it would be better to not document the URI space.

      I get the concept Roy is talking about, and it sounds cool. OTOH, if I just wanted to write a client to work with a small subset of a server's entities, I'd be damn annoyed if I couldn't find a direct way to get what I want.

      As far as AtomPub goes, it does seem like one would have to implement a full client to do anything with an AtomPub server that doesn't document it's URI space. You might point out that many AtomPub clients are exist, which is great for AtomPub, but not great for some other application which uses its own one-off media types.

      You're twisting Roy's words in his mouth. Atom feeds can contain the full data for each entry, and if you ask Roy what he thinks about AtomPub, he will tell you it is a great example of getting REST right. The salient point is that the Atom feed contains the URI of any entry that has one, and that is what you use to manipulate the entry if you want to do so.

      I'll take your word for it, but I was not twisting his words. He said that queries are represented by "a list of links with summary information". I'm not sure how else to interpret that.

      If he's just saying that results should contain URIs, then no shit. I thought that was obvious. But I'd also expect results to come with whatever information I asked for, not just a summary and a link.

      I blame ORA's REST book for my misunderstanding, at least in part. It really never discusses this aspect of REST. It does make the point that results should contain links, but it doesn't ever quite state the whole discoverability concept. It talks a lot about coming up with URIs, but never says that to document them as part of the API would be wrong.

      Unfortunately, it's the only thing I've found that talks about large parts of REST clearly, unlike Roy's writing, which is ridiculously academic. Much of the other REST stuff on the wiki (like on the REST wiki) is similar.

      • I imagine my media types would mostly be well-defined JSON “blobs”.

        Sure, that’s fine. Really, you don’t necessarily have to provide a specific media type; the core issue is that you document the response format, and that that format use links rather than application-specific IDs that the client must slot into URI templates which are never part of the in-band communication, and generally have to be built into the client at programming time.

        The other thing is, hopefully you would most