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.


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 9 July 2014 18:52:38 UTC