This post seems hyper-defensive and hyper-reactionary. URLs are fundamental to HTTP web services - they're how the web works. Imagine if you visited a website in your browser and instead of link to the various pages, the page just printed IDs and you had to copy/paste them into the address bar after the domain name.
Getting hyper about hypermedia APIs
21–30 of 73 posts
Re: Getting hyper about hypermedia APIs
#22Earlier quoted context omitted.
Your applicaiton's link relations should be URLs. This means that you can expose each bit of documentation for each rel at their URL. So every time you see a link in a hal+json document, you can follow the _rel's_ URL, and fetch the documentation for it.. that turns out to make the API very easily discoverable, and gives you a way to model/manage your API's documentation in a consistent way. You can actually see what…
Do you mean like http://haltalk.herokuapp.com/rels/signup ? But every site will have different requirements or mandatory fields on signup, so there's still no "discoverable" way to sign up to Amazon and eBay and Google without a human looking at http://amazon.com/rels/signup and http://ebay.com/rels/signup , etc., in which case you're back to still needing to read the documentation. I guess it's a slight improvement…
it is an example of a discoverable API with discoverable documentation though, which is what you were asking for I think.. maybe not?
Re: Getting hyper about hypermedia APIs
#23Bias alert: I'm the newest Rails committer and one of the bigger proponents of Hypermedia APIs in the Ruby world.
Anyway, many, many other companies _do_ find hypermedia principles to be useful. See Balanced Payments, for example:
> Fun fact: our internal statistics show that client libraries that construct the uri receive roughly 2 orders of magnitude more 404 status codes from Balanced than clients which use the uri directly. > > http://www.theatlantic.com/magazine/archive/1999/03/the-mark...
GitHub is starting to add hypermedia stuff to their responses:
Here's their main API guy talking about the advantages even this partial implementation has achieved: https://twitter.com/pengwynn/status/281849041707474944 https://twitter.com/pengwynn/status/281849329243787265
Twilio has always had elements of hypermedia in their API, and are considering moving further in that direction in the future. They had me speak at their conference for the last two years in a row about the topic specifically.
That said, if not doing hypermedia doesn't hurt you, don't change what you're doing! If you're interested in evolving your API over time while supporting old clients and behaviors in a simpler way, then consider checking it out. REST/hypermedia APIs are focused on long-term stability, evolvability, and massive scalability. If you don't need those things, you don't need hypermedia.
That said, I'd be happy to answer any questions on the topic, though I'm really busy today, so it might take a while to get back to you.
Re: Getting hyper about hypermedia APIs
#24hypermedia APIs mean that our API's basically become web pages and every client should act like a browser. That's great if you want... a browser app. If you want to just expose data to let people build interesting things with it, hyperlinks in your api are a bit silly. They might be nice if you want someone to write a browser for your api, I don't see where else it would be awesome. Maybe if you want a web crawler to…
So you could write an app against the API of some service, then a competitor of that service comes and implements the same API, and so you want to switch.
What should you do? Replace every URL? What if you want to support both (say, Twitter and Identi.ca)? Should you implement a map from codename ⇒ url?
Now what if you want to support every possible implementation, even if you - the developer - don't know about them? Why shouldn't the user be able to plug-in the entry URL and use your app?
People snickering about hypermedia APIs seem to me like people ridiculing the idea of having standard ports and protocols for devices, because they can't imagine a world where you don't have to install yet another crappy 200MB driver that is only available for Windows 95 to use a damned mouse.
Re: Getting hyper about hypermedia APIs
#25Wow. Very surprising (in a bad way).
Basic Web architecture: 1. expose resources, 2. resources have names (URL), 3. allow basic actions on these (GET, DELETE , PUT, POST ) as needed. 4. Include URLs (as links/forms) in representations.
OK, now build your API . Please do NOT start w/the API and work back to basic web architecture. Servers should always provide URLs (url templates are fine), NOT the client (by way of snowflakey construction algorithm).
Re: Getting hyper about hypermedia APIs
#26I 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 doesn’t have links."
JSON doesn't, but HTTP does. Why not use Link headers?
Re: Getting hyper about hypermedia APIs
#27I 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…
[deleted]
Re: Getting hyper about hypermedia APIs
#28According 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 nilly. It's that I, the client, can support a different API implementation by just changing the entry point URL, without changing the application.
So, if my application supports the API that Flickr implements, and tomorrow someone creates Blinkr, which implements the same API, the user could just copy-paste the entry point URL and use it, just like I use my RSS reader for all the blogs and news sites out there.
Of course, this depends on using standard document formats and a restricted, standard set of methods. Rings any bells?
Thinking that we can meaningfully derive all that by just telling people to GET / and then fumble around to discover all the options on their own just doesn’t gel with me.
Well, am I glad that straw-man was burned to the ground!
Re: Getting hyper about hypermedia APIs
#29Bias alert: I'm the newest Rails committer and one of the bigger proponents of Hypermedia APIs in the Ruby world. Anyway, many, many other companies _do_ find hypermedia principles to be useful. See Balanced Payments, for example: > Fun fact: our internal statistics show that client libraries that construct the uri receive roughly 2 orders of magnitude more 404 status codes from Balanced than clients which use the ur…
What are the best options to implement that for an API backend with Rails a javascript library/framework for the interface?
Re: Getting hyper about hypermedia APIs
#30I 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 doesn’t have links." JSON doesn't, but HTTP does. Why not use Link headers?
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 Cache Invalidation), but for normal APIs it makes your clients life much easier if you just put them in the body.