Re: Let us not say "API"

Wow, that turned from a cat fight into a philosophical treaty in one email!

I will agree with you that I don’t think we should separate out an API
section for the language reference.

Regards!

Julee
----------------------------
julee@adobe.com
@adobejulee




-----Original Message-----
From: Max Polk <maxpolk@gmail.com>
Date: Tuesday, December 3, 2013 at 5:14 PM
To: julee <jburdeki@adobe.com>, PhistucK <phistuck@gmail.com>
Cc: Renoir Boulanger <renoir@w3.org>, WebPlatform Public List
<public-webplatform@w3.org>
Subject: Let us not say "API"

> On 12/3/2013 2:54 PM, Julee Burdekin wrote:
>>  > ​I feel like operators, statements and literals should be within a
>>  > "language" sub path and the objects/properties/methods should be in
>>  > another sub path (the suggested "api" perhaps?).
> 
> This might turn into a vicious knock-down fight, replete with cat
> scratching ;-), but the "I" in API means "Interface".  An interface is a
> boundary between the language and a library.
> 
> "An application programming interface (API) specifies how some software
> components should interact with each other," (wikipedia), not how
> JavaScript interacts with itself.
> 
> In Java, the "Java API" is the built-in library that comes bundled with
> Java.  When you browse the Java API
> (http://docs.oracle.com/javase/7/docs/api/) you don't read about the
> language, you only read about the bundled library of useful routines.
> The library changes separately from the language in Java.
> 
> In most other cases, an API is an external library and you read the
> interface to the library (header files, WSDL, IDL, etc) that was
> published, then code to that interface by making library calls.
> 
> The phrase "web API" now refers to calls from your browser, frequenly as
> XHR requests, to a typically JSON web service.  You cross the boundary
> of the interface making the API call.
> 
> In JavaScript, there is no such segregation between language elements
> like operators and language elements like Math or Array. The word
> "library" only occurs in EcmaScript
> (http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf)
> in the context of implementators using a C or other library behind the
> scenes to undergird the language element Math.acos behavior.
> 
> It would also be confusing.
> 
> The prevalence of external libraries in JavaScript are the sole domain
> of the word "API", as in, code to the jQuery API (http://api.jquery.com/
> "jQuery API") or the Backbone.js API ("a rich API of enumerable functions").
> 
> To bleed boundaries and say part of the language elements are one thing
> and other language elements are on the other side is a mistake.  They
> are unified and one.
> 
> Furthermore, external libraries are so very commonly used in JavaScript
> (<script src="jquery.js"></script>) that it feels poor form to me to
> confuse language elements like Array and Math with calls to jQuery API.
> There is no interface you are crossing to access Array or Math in
> JavaScript.
> 
> Enough uses of the word API exist to warrant pause.  Let us not
> accidentally introduce for the *first time*, ambiguity and confusion.
> We should err on the strong side of this decision, not the weak side.
> 
> Words are symbols of critical importance for humans to understand. In
> the domain of the caretakers utmost diligence should be given to clean
> and unambiguous communication.
>