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.

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


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


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


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


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


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


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


> 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 16:48:35 UTC