Re: Let us not say "API"

I do not feel strongly about the name, it was just a suggestion made by
Rick and I followed it.

But, to continue this discussion -
While the language itself cannot be changed (operators, statements) while
the library/API/whatever, like Math, Object and the rest can be overridden,
which is why they should be differentiated, in my opinion.
I do not feel strongly about it. The uniqueness issue is scaring me here,
but nothing else.
"global" is just unhelpful and weird, on the other hand.
(Also, we have the "apis" top level path, which makes it consistent in a
way, which is why I followed the suggestion made by Rick.)


☆*PhistucK*


On Wed, Dec 4, 2013 at 5:37 AM, Julee <julee@adobe.com> wrote:

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