RE: Specifying operations for instances

> -----Original Message-----
> From: Markus Lanthaler [mailto:markus.lanthaler@gmx.net]
> Sent: Wednesday, July 09, 2014 5:48 PM
> To: public-hydra@w3.org
> Subject: RE: Specifying operations for instances
> 
> 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:
> >>>> documentation might state that the 'Products' class may support a
> >>>> 'Special Discount' operation, but a specific instance of 'Product'
> >>>> will only support that 'Special Discount' operation if the user
> >>>> associated with that instance is a 'Privileged User'...?).
> >>>
> >>> 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!).

> 
> >> I think the fundamental reason why this never occurred to me was
> >> simply because of my long history of working with API's in the
> >> traditional sense. By that I mean working with '#include <...>'
> >> header files in C and C++, and then using the keyword 'interface'
> >> in Java and C# (and the general guidance to 'always program to
> >> interfaces'),
> 
> Local computing and distributed computing are two completely different
> things. Unfortunately, it is quite hard to "unlearn" the habits/patterns when
> switching from local to distributed.
> 

Absolutely! Hence my comment above about how essential it is to explicitly explain to experienced developers the things that have to start 'unlearning' (such as considering API descriptions 'static').

> 
> >> and then using IDL in CORBA to define my APIs, and then using WSDL to
> >> do likewise for WS-*.
> 
> That's why RPC is so doomed. It tries really hard to treat local and remote
> computing exactly the same way.
> 

Yep.

> 
> >> In every single example of developing or using an 'API' throughout my
> >> entire career I've always been forced to work with a single
> >> *static* representation of an 'interface'.
> 
> Forced? It would be nice if it were like this on the Web as well :-P
> Unfortunately, when you access systems that you don't control things are
> dynamic and do change.
> 

Yep. So again that's why it's so important to repeat, over and over again if necessary, that developers need to unlearn their traditional notions of APIs when working with distributed systems (whether large-scale Web-based or just internal corporate systems).

> 
> >> I think this is the first time I've come across the concept of the
> >> API description itself being so dynamic [1], so dynamic in fact that
> >> potentially each and every consumer of that API might see a
> >> completely different representation of it at runtime!  I think that's
> >> a big paradigm shift for developers - but I totally agree with the
> >> premise.
> >>
> >> 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!).

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

> With traditional APIs the developer needs to know
> what can be done when and hardcode that knowledge into his application.
> The API won't change without the developer noticing it. On the Web, the
> "API" can change at any time because it is not under the developer's control.
> Thus hardcoding such knowledge into the client would break it. That's why
> we need to read the documentation at runtime instead of design time.
> 

Absolutely, which is why I'm saying the Hydra specification should state that very explicitly right up front, and emphasize it throughout.

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

> 
> >> 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 know a resource instance can always reject a request at runtime
> >>>> for 'Special Discounts' if the user is not 'Privileged' (and I know
> >>>> we have the open-world assumption to deal with here!), but I think
> >>>> like Tomasz I was kinda thinking of a UI that could be a bit
> >>>> friendlier than always offering the user every possible operation,
> >>>> but then returning errors to them when they attempt operations that
> >>>> the server-side probably knows already that they can't actually
> >>>> perform
> >>>
> >>> There are multiple ways to achieve that:
> >>>   - just use inline operations
> >>>   - use inline operations for things that vary by user/instance/etc.
> >>>   - serve different API documentations for different users
> >>>   - use multiple classes and use them accordingly (Comment,
> >>> RemovableComment)
> >>>
> >>
> >> Yep - plenty of avenues there alright. I get it now!
> >
> > Indeed it was just as enlightening to me as well! The way Hydra
> > empowers developers to build dynamic or generic systems is great.
> > Though I still cannot fully agree that developers will never want to
> > read the API representation (be it a JSON-LD document or generated
> > HTML documentation). We are humans after all and humans will
> implement
> > client systems.
> 
> Oh, they will. I just would like to reduce the cases where they have to.
> 

And so again, stating that explicitly in the spec is important I think. Telling developers that they shouldn't even need to read the documentation is a fantastic enticement to any curious developer to delve deeper into these concepts and ideas, and thereby encourages them to at least start unlearning some of their 'legacy' programming habits :) !

> 
> > I think it's great that we are closing in on a solution with the issue
> > Markus has created [1]. Shall we move to a new thread? Markus, would
> > you start one so that we can see whether we are on the same page and
> > go from there?
> 
> Feel free to start a new thread (and please include ISSUE-59 in the subject
> somewhere if you do so). I don't have much to add at the moment.
> 
> 
> > [1] https://github.com/HydraCG/Specifications/issues/59

> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
>

Received on Wednesday, 9 July 2014 18:23:12 UTC