Are Hypermedia APIs appropriate for all domains?
Anders
Do you think that Hypermedia APIs should always be chosen or are Level 1 and 2 HTTP APIs more appropriate for some domains? For example, could Twitter have benefitted from a Hypermedia API to reduce or eliminate the number of broken clients when they version their API?
Regards, Anders
mca
--
You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
Visit this group at http://groups.google.com/group/hypermedia-web?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
Mike Kelly
> Hypermedia APIs \should be used when this approach elicits system properties
> that you are aiming for. For example HAPIs usually promote modifiability
> properties like evolvability, extensibility, and reusability. These come at
> a cost (usually increased generality of interfaces, complexity or
> response-handling, added chance of request failures, etc.).
>
> The cost (time/effort/money) of change is probably the most common way ppl I
> work with decide if HAPI is a good idea. If there are lots of changes in the
> implementation, lots of client implementations, very low co-ordination of
> deployments (e.g. existing third party apps you don't "own") then the cost
> of change can be high.
>
> However, if you control all the code (client and server), can manage change
> mono-lithically (no need to co-operate w/ other stakeholders), and have a
> fully coordinated deployment model ("we'll be down saturday night while we
> deploy the new updates") then HAPIs are proly not much of a benefit.
>
> There are likely other measures, system properties, etc. to consider. These
> are the ones that come up most often in my work.
Cheers,
M
mca
M
Steve Klabnik
Kevin Swiber
I love watching this thread on two different lists. I should have split up my reply and put the other half here. :)
Anders
Thanks for the quick reply. I should clarify that my focus is on public web APIs by for-profit platforms. In the ecosystems that platform APIs enable, properties such as evolvability, extensibility and reusability are obviously very important. But so are network effects (both direct and indirect). To instigate network effects, API adoption is necessary. I'm wondering whether API adoption can be hampered by 1) the complexity of implementing a hypermedia client, and 2) the fact that many developers are much more familiar with standard level 1 and 2 APIs?
Best Regards,
Anders
Anders
mca
Mike Schinkel
be sure to include things you mentioned like "network effects", "adoption", "retention", 'ease of use", "time-to-build", etc. Twillio has some interesting things to say on this.
Would love to read that, if you have (a) link(s)?
Steve Klabnik
The other list I refer to is the one for my book, hyper...@librelist.com.
mca
--
Mike Schinkel
yeah, i knew when i wrote that that i'd need to dig back to find my links.ATM i can't (booo)this is one that i had on hand:toward the bottom is where the API Evangelist and things start to come into play. You can hit up Keith Casey directly (https://twitter.com/CaseySoftware) and he'll give you a great story on this.once i get my materials together, i promise to post more.
Peter Williams
On Apr 4, 2013 2:00 PM, "mca" <m...@amundsen.com> wrote:
>
> However, if you control all the code (client and server), can manage change
> mono-lithically (no need to co-operate w/ other stakeholders), and have a fully
> coordinated deployment model ("we'll be down saturday night while we deploy the
> new updates") then HAPIs are proly not much of a benefit.
I wonder if this undersells the benefits of hypermedia a bit. Aren't you effectively suggesting that in many situation it is appropriate to tightly couple at least two layers of the architecture? This is, of course, potentially true but when we say something like this about software design we usually preface it with some point about the dangers of premature optimization and follow it with a reminder that the listener almost certainly doesn't have the kind of performance problems that would require such a dramatic and costly solution. As an industry we have found that loosely coupled, highly cohesive modules are usually preferable. Given that hypermedia APIs tend to reduce coupling between the client and server should we hedge quite this much?
Peter
Barelyenough.org
Ps: Ime, the reduction in connasence provided by hypermedia has been well worth the cost even on projects where my team owned both the client and server and could change them in lock step. Clean, loosely coupled interfaces just make maintenance less costly. That that goes double if the interface is between code bases, languages or even processes.
Glenn Block
http://kellabyte.com/2011/09/04/clarifying-rest/
I think it could provide benefit to their API for the reasons you cite.
From: Anders
Sent: 4/4/2013 11:37 AM
To: hyperme...@googlegroups.com
Subject: Are Hypermedia APIs appropriate for all domains?
Do you think that Hypermedia APIs should always be chosen or are Level 1 and 2 HTTP APIs more appropriate for some domains? For example, could Twitter have benefitted from a Hypermedia API to reduce or eliminate the number of broken clients when they version their API?
Regards, Anders
Mike Kelly
Fwiw, my experience is basically the same.
I think the cost benefit wrt m2m does depend quite a lot on how easy it is to write code that interacts with the hypermedia controls you're introducing, and how that weighs up against the degree to which each of those controls actually reduces connasence for the type of evolvability challenges that need to be overcome _in practice_.
For example, many form-like hypermedia controls in existing types don't really solve any serious m2m challenges I've seen since they merely shift connascence of name into the client's interaction with the form but don't actually reduce it in any way.. The clients are now just coupled to the names of the inputs in the form instead of , say, the names of the json properties in the request. Yes the values in the resulting request body can be renamed, but ime being able to change this is not hugely important. At least not important enough to make the clients incur the cost of jumping through a hypermedia-form-submission hoop.
To put it another way.. from a developer-writing-a-client's point of view; adding a form control means she goes from figuring out what json properties she has to POST, to figuring out what form inputs she needs to submit (between which there's no real difference).. Oh and she also now is forced to implement non-trivial code for correctly interacting with a form control.
That's a tough sell. Its definitely not a good user experience. Its the kind of thing that can lose you customers.
This is in contrast to the use of simpler controls like links and templated links which actually do reduce costs for clients - no coupling to uri patterns, no uri construction logic. They also afford the server to enact granular evolution of the api where breaking changes and new features can be introduced seamlessly simply by adding a new link.
But hey, I would say that because its the justification for why hal+json is the way it is! :)
Cheers,
M
Markus Lanthaler
> To put it another way.. from a developer-writing-a-client's point of
> view; adding a form control means she goes from figuring out what json
> properties she has to POST, to figuring out what form inputs she needs
> to submit (between which there's no real difference).. Oh and she also
> now is forced to implement non-trivial code for correctly interacting
> with a form control.
>
> That's a tough sell. Its definitely not a good user experience. Its
> the kind of thing that can lose you customers.
>
> This is in contrast to the use of simpler controls like links and
> templated links which actually do reduce costs for clients - no
> coupling to uri patterns, no uri construction logic.
templates links are any simpler than forms (or different at all for that
matter). They incur exactly the same costs: you have one additional
indirection.
According to you, what's are the differences between a form field and a URI
template variable?
Cheers,
Markus
--
Markus Lanthaler
@markuslanthaler
mca
--
Jason Erickson
That was my theory, but the consumers of the API were definitely NOT grateful. Parsing JSON is VERY easy, and while XHTML is technically XML, all of the tags are HTML tags and if you want to get semantic information out, you have to look in class attributes (similar to micro formats) or use some non-standard attributes or something, so parsing XHTML for semantic information, while I'm sure is easy for someone who does it frequently, was not familiar to the developers I was dealing with who were used to dealing with JSON and XML.
In theory, theory and practice are the same, but in practice…
Moore, Jonathan (CIM)
In our case, we offered a thin client library that handled extracting HTML microdata, finding links, submitting forms, etc. Given this interface, the fact that the underlying transport is HTML is largely hidden, and in fact the APIs become very easy to work with.
I gave a talk at QCon London recently about this experience:
http://qconlondon.com/london-2013/presentation/Building%20Hypermedia%20APIs%20with%20HTML
The video should be available after June 17:
http://qconlondon.com/london-2013/videos
In that talk I used a demo Python client library of this general form, which I've (just) gotten approval to release as open source. I'll be sure to post a link here once I get it up.
Now, an interesting vignette: after the experience of building and operating our first HTML-based API, the API team was very excited to use these concepts for their next project, which was meant to power mobile client apps. The iOS team fairly flat out refused to even try an HTML-based API, demanding JSON. Since we wanted to ship software more than we wanted to argue, we decided to use HAL+JSON instead.
That has generally worked out well, although we have found we've had to "reinvent" certain features HTML provides--figuring out how to achieve the same thing in HAL (URL fragments to point to inner parts of responses being a good example). The mobile client teams have become more comfortable with the idea of hypermedia APIs in general, though, and the last time I ran into the iOS tech lead he opined that if he had to do it over he would have preferred an XHTML representation. Quite a turnaround.
While I do think HTML makes a ton of sense for hypermedia APIs, I think this is a "point in time" assessment. The community is actively working on JSON hypermedia formats and I do not debate that it is easier to work with parsed JSON structures than the DOM of parsed HTML, so I think we'll see that come to fruition. In my experience, though, I'll need a JSON format that provides all of the following before I'd switch my recommendation:
(a) support for semantic annotations, e.g. microdata, RDF, etc.
(b) support for interior representation links
(c) support for embedded or remote properties
(d) support for links
(e) support for forms [1]
(f) good browser tooling (could be plugins)
Jon
[1] I think that URI templates aren't solely sufficient, as sometimes you want to construct an HTTP request that POSTs (or, if we get our way with the HTML spec, PUTs) to a specific URI where the inputs are carried in the body, primarily for cache invalidation reasons.
________________________________________
From: hyperme...@googlegroups.com [hyperme...@googlegroups.com] on behalf of Jason Erickson [jason.h....@gmail.com]
Sent: Monday, April 08, 2013 4:18 PM
To: hyperme...@googlegroups.com
Subject: Re: Are Hypermedia APIs appropriate for all domains?
Mike Kelly
We've built an HTML-based API are are using it in production, and I think you have definitely touched on some pain points.
In our case, we offered a thin client library that handled extracting HTML microdata, finding links, submitting forms, etc. Given this interface, the fact that the underlying transport is HTML is largely hidden, and in fact the APIs become very easy to work with.
I gave a talk at QCon London recently about this experience:
http://qconlondon.com/london-2013/presentation/Building%20Hypermedia%20APIs%20with%20HTML
The video should be available after June 17:
http://qconlondon.com/london-2013/videos
In that talk I used a demo Python client library of this general form, which I've (just) gotten approval to release as open source. I'll be sure to post a link here once I get it up.
Now, an interesting vignette: after the experience of building and operating our first HTML-based API, the API team was very excited to use these concepts for their next project, which was meant to power mobile client apps. The iOS team fairly flat out refused to even try an HTML-based API, demanding JSON. Since we wanted to ship software more than we wanted to argue, we decided to use HAL+JSON instead.
That has generally worked out well, although we have found we've had to "reinvent" certain features HTML provides--figuring out how to achieve the same thing in HAL (URL fragments to point to inner parts of responses being a good example).
The mobile client teams have become more comfortable with the idea of hypermedia APIs in general, though, and the last time I ran into the iOS tech lead he opined that if he had to do it over he would have preferred an XHTML representation. Quite a turnaround.
Mike Kelly
direct requests onto new servers by changing the domain, which allows
you to leverage DNS to move client transitions around your system i.e.
it's value is more than simply renaming things.
Also, URI templates do actually present an easier experience for most
developers at this point. There are established URI template libraries
for most major languages. This means that clients do not need to
create (and maintain) URI construction functions, and so the client
only has to know the variables it needs to expand a given URI
template.
As I mentioned in the previous post, the above is not the same with
request body templates (aka 'forms'):
Practically speaking, without a form clients will construct the set of
properties they want to represent in the body and then pass that set
to some JSON serialiser (which are ubiquitous at this point). Now if
you look at the case where you introduce forms, the client still has
to construct a set of properties that it wants to represent in the
body, but instead of using a ubiquitous JSON serialiser - it is now
forced to pass this to some form submission library that may or may
not already exist.
This doesn't reduce the effort for the client, but it arguably
increases it because now their code depends on a relatively new and
poorly understood library for submitting forms. Oh and debugging just
got more difficult due to the run time indirection of a form.
It also doesn't afford the server anything other than being able to
rename a few properties in the body of the request. Accommodating
server-side-developer OCD should not rank highly on your priority
list. :)
I just can't see the value of forms in m2m APIs. If you're doing GUI
stuff, please just use HTML.. that's what it's there for.
Cheers,
M
Kevin Swiber
> <snip>
This is interesting. We just had a use case for this pop up on the Siren hypermedia list. In general, there's no "anchor" concept in any of the JSON hypermedia formats (if I recall correctly).
There was a suggestion of adding a "name" property to entities that could accommodate such a thing. Would you mind sharing the solution you used? JSONPath, perhaps?
Thanks,
Steve Klabnik
Markus Lanthaler
> [...]
> While I do think HTML makes a ton of sense for hypermedia APIs, I think
> this is a "point in time" assessment. The community is actively working
> on JSON hypermedia formats and I do not debate that it is easier to
> work with parsed JSON structures than the DOM of parsed HTML, so I
> think we'll see that come to fruition. In my experience, though, I'll
> need a JSON format that provides all of the following before I'd switch
> my recommendation:
>
> (a) support for semantic annotations, e.g. microdata, RDF, etc.
> (b) support for interior representation links
> (c) support for embedded or remote properties
> (d) support for links
> (e) support for forms [1]
> (f) good browser tooling (could be plugins)
the documentation still needs some love)? Looks as the combination of the
two would address all of your requirements. There's also a prototype
browser/API console [3].
Feedback would be much appreciated.
[1] http://www.w3.org/TR/json-ld/
[2] http://m.lanthi.com/HydraED
[3] http://m.lanthi.com/HydraConsole
--
Markus Lanthaler
@markuslanthaler
Moore, Jonathan (CIM)
I was aware of JSON-LD but hadn't seen Hydra yet. I'll be sure to check it out. Are the two specs compatible?
Jon
........
Jon Moore
Markus Lanthaler
> I was aware of JSON-LD but hadn't seen Hydra yet. I'll be sure to check
> it out. Are the two specs compatible?
define a profile which eliminates most of the variability so that also
clients that just understand JSON (but not JSON-LD) are able to use of it.
--
Markus Lanthaler
@markuslanthaler