Re: Specifying operations for instances

----- Original Message -----
> From: "Markus Lanthaler" <markus.lanthaler@gmx.net>
> To: public-hydra@w3.org
> Sent: Wednesday, July 9, 2014 12:52:05 PM
> Subject: RE: Specifying operations for instances
> 
> On 9 Jul 2014 at 20:22, McBennett, Pat wrote:
> > Markus Lanthaler wrote on July 09, 2014 5:48 PM:
> >> On 8 Jul 2014 at 13:35, Tomasz Pluskiewicz wrote:
> >>> On Tue, Jul 8, 2014 at 1:16 PM, McBennett, Pat wrote:
> >>>> Markus Lanthaler wrote on July 07, 2014 6:51 PM:
> >>>>> This can be addressed by serving different API documentations to
> >>>>> different users.
> >>>> 
> >>>> Wow - this sentence was a huge light-bulb moment for me :) ! I simply
> >>>> never thought of the API documentation in that way, and checking the
> >>>> Hydra specification again, I can't find any direct explicit
> >>>> references to such an interpretation.
> >> 
> >> We could certainly add a statement mentioning this.
> >> 
> > 
> > 'Could'? I think this is essential, especially as both myself and Tomasz
> > took
> > so long to realize it, and in fact I think it really captures a fundamental
> > difference
> > between a genuinely RESTful API and a 'traditional' API (and does so very
> > succinctly!).
> 
> OK. I've added a comment to ISSUE-59 so that we don't forget it
> 
>  
> >>>> So it leads me to think that simply calling this the 'API
> >>>> Documentation' is in fact a very misleading misnomer, given the
> >>>> automatic association any experienced developer (like me) will have
> >>>> between an API and some static description (in fact, in my mind 'API'
> >>>> almost seems to *mandate* a large degree of static-ness!).
> >> 
> >> API isn't the best term but unfortunately that's the term most people use
> >> for
> >> these "service interfaces".
> > 
> > But my point is that API is the term most people use to describe something
> > *completely
> > different* - i.e. they use that term to describe 'traditional' APIs that
> > have always (without
> > exception) been 'static' by their very nature (until the next version comes
> > along of course -
> > i.e. DLL-hell!).
> 
> I think Web APIs and Hypermedia APIs are two well established terms by now
> even though API by itself means something entirely different. I'm not
> convinced that it makes a lot of sense to use introduce a different term. I
> think it makes more sense to describe the difference (as you did above) in a
> couple sentences in the spec.
> 
> 
> >> On the other, it isn't the case that the interface
> >> changes all the time. It is *quite* static in most cases but a user
> >> might not have access to everything.
> > 
> > Very true, but isn't the '*quite* static in most cases' nature of
> > RESTful interfaces a dangerous thing to even mention initially.
> > Personally I'd leave that detail to the end of any discussion -
> > almost like an optimization. If any developer senses that an API
> 
> Absolutely. It is an optimization and is called caching.
> 
> 
> > will be 'mostly static', or 'static most of the time' then they'll
> > be very tempted to fall back to their familiar local-system
> > thinking, and therefore start 'hard-coding for now' and we'll start
> > drifting back to where we are today with brittle systems...
> 
> Yeah. Probably the intro of section 3 in the spec should emphasize this a bit
> more:
> 
>    http://www.hydra-cg.com/spec/latest/core/#hydra-at-a-glance
> 
> 
> >>> My thoughts exactly. I even had an unsent draft with the exact same
> >>> conclusion and programming API analogy as well. The word document is
> >>> derived from latin documentum - example, which shares the stem doc-
> >>> with the word docere - to teach [1]. In that sense I think most people
> >>> will intuitively understand the ApiDocumentation as a place to learn
> >>> from.
> >> 
> >> So the term ApiDocumentation isn't that bad after all :-)
> >> 
> > 
> > Well, yes it is still 'bad', 'cos any developer coming across it for
> > the first time will naturally think of '#includes', or Java
> > interfaces, or CORBA IDL, or WSDL (they've no choice, as they're the
> > only APIs that they've ever seen). Using the terms DAPI and DAPID
> > (Dynamic Application Programming Interface Documentation) on the
> > other hand would force them to investigate what's different here,
> > hence leading them to at least think about the need for truly
> > dynamic interfaces.
> 
> Most developers are busy people and the thing they are most interested in is
> to get their job done. There are already quite a lot of things that Hydra
> does differently than anything else and thus require more research. We need
> to start with something developers are already familiar with to gradually
> introduce to Hydra.
> 
> 
> >>>> Instead I really like the idea of expressly describing Hydra as a
> >>>> vocabulary for describing 'Dynamic Application Programming
> >>>> Interfaces' - i.e. a DAPI, and *not* an API (nor a 'Dynamic API', see
> >>>> [1]). This seems like an opportunity to introduce a new acronym
> >>>> (DAPI) to try to very explicitly and clearly express the fundamental
> >>>> difference between traditional APIs based on the Closed World
> >>>> Assumption, and DAPIs based on the Open World Assumption...
> >> 
> >> There already exists a quite similar acronym, DAP, which describes this
> >> already:
> >> 
> >>    http://en.wikipedia.org/wiki/Domain_Application_Protocol
> >>
> >> Unfortunately, very few people are familiar with this term. Thus I decided
> >> to
> >> call this thing simply a ApiDocumentation.
> >> 
> > 
> > Even though I've read that book (REST in Practice), the term DAP didn't
> > really resonate with me. It doesn't communicate the truly 'dynamic'
> > nature of the interfaces we're trying to describe and document here (and
> > anyway, any API, whether static or dynamic, is going to inherently
> > define a 'domain application protocol', so it's not helping to
> > differentiate anything for me). But I don't think falling back to simply
> > using API is going to help either, as I can definitely see many other
> > developers falling into the same misconceptions as myself and Tomasz.
> 
> I see it from a different perspective. A developer has a problem to solve,
> namely "to build a Web API". Since there aren't any well-established
> processes and standards to do so yet, typically the next step is research.
> So the developer goes to his favorite search engine and looks for
> approaches/technologies/tools/... to build a Web API. Typically this leads
> to long list of candidates HAL, Siren, JSON-LD, Hydra, RAML, Swagger, ...
> Obviously, there isn't enough time to really get to know each approach
> properly so most specs are just skimmed. A few are considered worth a closer
> look. In the end, most developers then decide that all of these approaches
> are "nice in theory" but they need something else and that they already
> wasted way too much time to do all this research and so they simply stick to
> plain old JSON.
> 
> I'm very concerned that introducing new terminology such as DAPIs we lose
> developers too early. We can explain this things in prose but the major
> keywords developers are familiar with need to be there to convince them that
> Hydra is worth a closer look.
> 

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? 

I also think that even though the terms API and REST are the most misconstrued and ambiguous terms in the history of the web, we should use them, along with Hypermedia API and Web API (or hypermedia-driven Web API). That is what developers will be looking for.

Received on Wednesday, 9 July 2014 19:48:11 UTC