W3C home > Mailing lists > Public > public-hydra@w3.org > July 2014

Re: Is the term ApiDocumentation misleading (ISSUE-61) / was: RE: Specifying operations for instances

From: Chris Chapman <chris@pentandra.com>
Date: Thu, 10 Jul 2014 10:47:20 -0600 (MDT)
To: public-hydra@w3.org
Cc: Markus Lanthaler <markus.lanthaler@gmx.net>
Message-ID: <42786177.689.1405010840324.JavaMail.zimbra@pentandra.com>
----- Original Message -----
> From: "Markus Lanthaler" <markus.lanthaler@gmx.net>
> To: public-hydra@w3.org
> Sent: Thursday, July 10, 2014 5:29:40 AM
> Subject: Is the term ApiDocumentation misleading (ISSUE-61) / was: RE: Specifying operations for instances
> 
[...]
> > >  I was that developer not too long ago, and found things like HAL,
> > > Siren, api+json, Collection+json, Collection.Doc+json but found all
> > > of the approaches based on media types too constraining. I knew
> > > enough about code generation to steer clear of Swagger. Never heard
> > > of RAML. JSON-LD seemed like it had some good things going for it,
> > > and could possibly serve as a basis for something that could work...
> > > I think I may have stumbled across Hydra in my research, but at the
> > > time it didn't look finished and it had this stuff about
> > > ApiDocumentation, and I thought, isn't the point of REST to get rid
> > > of all this API documentation? So I didn't look into it further.
> > > Since rediscovering Hydra a few months ago I have learned that the
> > > ApiDocumentation is for the machine, not for the developer per se.
> > > And that is OK, I think (though I've tossed around the term
> > > ApiDescription). But it may be good to clarify that (early) in the
> > > spec if it is not already?
> 
> Yeah, these discussions really indicate that this has to be clarified in the
> spec. I assume both of you actually took the time to read the spec.. did
> you? :-)
> 

Yes, Markus :P, but at the time I was trying to compare 10 different options, and I had only an incomplete understanding of any of them. I was mainly looking for ways to eliminate possibilities. Short-term fail on my part ;) 

Chris
Received on Thursday, 10 July 2014 16:48:26 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:29:42 UTC