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

----- 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