Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Getting hyper about hypermedia APIs

37signals.com

Post reply on HN
Print view View original

51–60 of 73 posts

Re: Getting hyper about hypermedia APIs

#51

Post by mahmoudimus »

icebraining wrote: post #28

According to hypermedia lore, you will be able to willy nilly change your URLs without needing to update any clients. But that’s based on the huge assumption that every API call is going to go through the front door every time and navigate to the page they need. That’s just not how things work. This is missing forest for the trees. The point is not that you, the API implementor, will be able to change URLs willy nill…

I'm the CTO @ https://balancedpayments.com.

This is exactly the case. We asked our customers to store the URIs in their databases and we ended up changing core resource locations and migrating older clients by just issuing 301s.

The extent was that we restructured entire URLs, changed endpoints. Hypermedia is baked into our clients from the start and they make API versioning and updates trivial.

We were able to quickly move customers to different endpoints and easily restructure our API without having to worry about backward compatibility.

Hypermedia APIs are a godsend. There's still lots of work to do and I'm happy to contribute to adoption.

Re: Getting hyper about hypermedia APIs

#52

Post by irickt »

MattRogish wrote: post #4

Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s. "If we just use RDF triples to encode everything then machines can learn that apples are fruits and fruits are good for you, thus apples are good for you! Huzzah!" Then, Microsoft invented SOAP. "If we just have a WSDL that explains all of our API, then we can have automated methods to communicate between services! Prog…

You may be surprised that the semantic web continued to develop after you dismissed it, the latest milestone being Google's Knowledge Graph.

http://news.ycombinator.com/item?id=3983179

Re: Getting hyper about hypermedia APIs

#53

Post by steveklabnik »

mahmoudimus wrote: post #47
steveklabnik wrote: post #33

Earlier quoted context omitted.

The current Rails Party Line is "Jbuilder + you don't need integration" https://twitter.com/dhh/status/281802247480958976 https://twitter.com/dhh/status/281802391316201472 Some members of the core team and I have started a "Rails API" project specifically to explore these possibilities, and to extract common patterns from the apps we build: http://github.com/rails-api This will encompass hypermedia and non-hypermedia…

We also have developed custom Python tools and frameworks that help us with our API at https://balancedpayments.com/ If there's enough interest, I'd love to share some of our ideas with the Rails community and discuss some potential downfalls and successes we've had and why we needed to build these tools internally. I'm sure Rails would benefit a lot from these. Love love love the hypermedia work -- keep it up!

That would be fantastic. If you find the time, we have a discussion list over at https://groups.google.com/forum/?fromgroups#!forum/rails-api... , please feel free to share thoughts there!

Re: Getting hyper about hypermedia APIs

#54

Post by mamcx »

I use http://www.remobjects.com/ro/, and have something similar, called RODL Files (http://wiki.remobjects.com/wiki/RODL_Files), this is how look like:http://wiki.remobjects.com/wiki/RODL_Library_(Service_Builde.... This are like SOAP, but better. With them, I can parse the RODL file, and build a python client automatically in seconds, with a python script that output a python client for the remobjects server, with all the class, method calls and that stuff. RemObjects also generate automatically the clients for .net, delphi, js, obj-c, php (http://wiki.remobjects.com/wiki/Generating_Interface_Code_fr...). Is something I miss very much when try to do a REST server without RO.

And the documentation is embebed in the RODL file, so is possible to output the client with the docs inline, and get it to show in the IDE when a call is made to the python client...

So, I think a meta-data about the service is VERY usefull. But the hypermedia is a poor attempt at that (IMHO).

Re: Getting hyper about hypermedia APIs

#55

Post by bct »

MatthewPhillips wrote: post #39
AffableSpatula wrote: post #30

Earlier quoted context omitted.

Link header parsers are far less ubiquitous than json, and Link headers aren't very good for use cases like representing links that come from items in a collection, there are also issues relating to the maximum feasible size for HTTP headers and/or the header block as a whole. Link relations are useful for adding links to media types that can't support links (e.g. images, etc), and for layering protocols (e.g. Linked…

Would this be a better fit as part of an OPTIONS request? OPTIONS /orders { "GET": { "description": "All the orders." "links": { "self": { "href": "/orders" }, "next": { "href": "/orders?page=2" }, "find": { "href": "/orders{?id}", "templated": true }, "admin": [ { "href": "/admins/2", "title": "Fred" }, { "href": "/admins/5", "title": "Kate" } ] } } }

Here's one opinion on that: http://www.mnot.net/blog/2012/10/29/NO_OPTIONS

Re: Getting hyper about hypermedia APIs

#56

Post by steveklabnik »

kodablah wrote: post #14

Sounds like a redefinition of HATEOAS. I don't put URLs as my ID's, but every resource has an "href" value which is the URL which makes it somewhat discoverable by tools such as https://github.com/jed/hyperspider .

"Hypermedia APIs" are just "Real REST." Arguing over terms isn't productive, so many RESTafarians just stopped: http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over

HATEOAS sounds big and scary. "include some links" is much more understandable.

Re: Getting hyper about hypermedia APIs

#57

Post by dribnet »

jashkenas wrote: post #17

One neat trick that I think is worth adding to the discussion: URL templates. Returning URL templates as part of your API response can give you the benefits of having a clean way to access sub-resources, without the headaches and bloat of having to enumerate every possible desired sub-URL. For example, in DocumentCloud, a document's canonical representation has a unique URL for the content of every page as plain text…

> One neat trick that I think is worth adding to the discussion: URL templates.

100% agree - URL templates enable succinct discoverability. Moving link generation to the client reduces computation time on the server which no longer has to generate inline links as well as the payload size of the response.

The RFC6570 spec is great, has numerous implementations[1] and a through test suite[2]. I am also surprised that this is not a standard part of every hypermedia implementation.

[1] http://code.google.com/p/uri-templates/wiki/Implementations

[2] https://github.com/uri-templates/uritemplate-test

Re: Getting hyper about hypermedia APIs

#58

Post by masklinn »

jalfresi wrote: post #48
AffableSpatula wrote: post #2

I wrote the spec for application/hal+json that got compared to WS-star , here's where I'm coming from: JSON doesn’t have links. Establishing some basic conventions for that makes complete sense. Defining those conventions is called a spec. Giving a payload that follows conventions a name also makes sense. Establishing that is called registering a media type identifier. It makes no sense to keep reinventing the linkin…

JSON and other non-natively-hyperlinked-media (e.g PNG, MP3, etc) can use the Link header to add hyperlinks. It's HTTP that is hypermedia aware, not the content-type, so you dont have to go out and invent image/png+hal. TL;DR You dont need to create a new media-type to make JSON hypermedia. All requests are hypermedia by virtue of the fact that it uses HTTP as the transport protocol.

> It's HTTP that is hypermedia aware, not the content-type

1. That's highly debatable, the very content type from which REST was extracted is hypermedia-aware

2. The LINK header only works for very shallow and broad linking, making it contextual to the content type will have as high a complexity (if not higher) as codifying hypermedia in the content type (consider a resource listing other resources, the equivalent to the HN frontpage, how are you going to match a given entry in the media — which may have a number of inline metadata — to its LINK? anchor? now you need to define an anchoring scheme in your content type. A link-extension? Now you need to define that, and you need to define the relation between the link extension and the content type. And of course you also need a custom relationship, which you'll also have to define, and you need your clients to correctly handle upwards to hundreds of LINK in a single resource) (and even with that, you're also making the client more complex because he'll need an explicit link-resolution step... and then, are URI templates allowed at all in a LINK?)

Re: Getting hyper about hypermedia APIs

#60

Post by fbuilesv »

gamache wrote: post #5

DHH's API philosophy (send simple JSON serializations over the wire, mostly from the server to the browser) got him through the 2000's OK, but the longer he argues against hypermedia, the less relevant Rails becomes for API design. These are not particularly good arguments he puts forth here. I believe they are in response to Mike Kelly (designer of the HAL+JSON hypermedia format) and his recent post: http://blog.sta…

These are not particularly good arguments he puts forth here

Would you care to explain why you think they're not particularly good? You're blaming DHH of being "hand wavy" but I don't see any more depth from your comment.

Post reply on HN