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.

Received on Wednesday, 4 December 2013 01:14:31 UTC