A post of mine here on dev.to ignited a furious debate around the meaning of "API". In this post I'd like to expand more on the subject.
A bit of backstory
I don't like at all the "50 things you should know" kind of posts, but I thought I would make a gift to the community with my "27 Web Development Terms You Should Absolutely Know About".
Long story short, I had the gut to say that document.querySelector() is an API. Here's my original definition:
Native API: a native API is a built-in function available by default in a programming environment. Speaking of browsers for example we say that document.querySelector() is an API for selecting HTML elements.
A reader promptly commented:
I stopped at Native API, this is not even close to being correct
Another reader told me:
You are very enthusiastic what is not a bad thing except when is not backed by proper knowledge. It would also help to ask someone to proofread before publishing, both linguistically and technically.
I already knew that my english is not so good, after all it's not my mother language, but ehi, I'm working on this too!
Being immune to non-constructive criticism I always overlook these kind of comments, yet it's funny how a complete stranger can assess your experience (I won't brag about my 21 years in web dev as another reader did) just by looking at your writing.
Anyway, back to our main topic: the API.
Is document.querySelector() an API?
So what is document.querySelector()? Is it a function? Is it an API? Technically speaking it is a method of the document object. Methods are functions bound to an object.
querySelector() in particular is a method for selecting HTML elements in the DOM.
But guess what, I'm not wrong either when I call it API. I'm really sorry for your dear reader. Web development, and programming in general are full of elusive terms.
Think of testing for instance: after 30 years there's still no consensus on the meaning of "unit testing". Some people says it's the test for a single class, or for a single function. Other folks say it's the test for a unit of work, which is no longer a single function anymore (if your curious check out "The art of unit testing").
I was curious to know if I'm the only fool who refers to a single methods as API, and here's what I found. This comes from Nicolas Bevacqua, a prominent figure in the JavaScript community:
In "JavaScript application design" Nicolas says:
A prime example of using callbacks is found in the addEventListener API
For those new to browsers and JavaScript, addEventListener is a method which any HTML element borrows from EventTarget.prototype.addEventListener.
addEventListener is a method, but it's also an API, that is, a surface that the developer can interact with.
The API strikes again!
So what's an API really?
If you were to "Google it", API is:
a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.
Stricly speaking API stands for application programming interface, that is, a set of functions (or methods) acting as the gateway between the developer and the underlying system.
Yet if I were to remove the word set, the definition would become:
functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.
After all document.querySelector and Event.prototype.addEventListener aren't gateways between the developer and the underlying system?
Still they're not a set of functions if you take those methods one by one, yet I feel they're the surface of a more complex system (respectively the DOM and the event-driven architecture found in browsers).
That's exactly what an API is for me: a surface.
If that's an heresy for you, don't take it personally. We could still be friend.
Conclusions
We ought to be rigorous when teaching to beginners, but I also think that introducing someone to a shallow definition of an elusive term doesn't make any harm in the long run.
Or it will. And for that I consider myself guilty. But I don't think that beginners, and developers in general should be treated as idiots unable to spot the difference between a proper application programming interface and the term API applied to a single point of contact.
With time they will found out.
Be kind to others and happy coding!
Resources
The original post: 27 Web Development Terms You Should Absolutely Know About.
MDN documentation on Web APIs and interfaces.
Application programming interface on wikipedia.
Originally published on my blog
Top comments (6)
After reading the original post I agree that some people are just being pedantic. Whether querySelector is an API or part of an API I think it is just semantics. It doesn't matter. It is part of an exposed interface we can use to communicate between two pieces of software. I have seen the API acronym used in plural and singular to refer to similar things.
However. I think your definition of Native API is perhaps not the appropriate term. I would argue querySelector is part of the browser Web APIs and that is a more appropriate term. When I hear Native API I think the APIs that interact with the hardware/kernel by directly calling the OS. I would call the win32 API or the Android API a native API but not querySelector or document, or any of the browser web APIs. They are one level of abstraction up from native APIs the OS exposes. Native to me means OS-specific.
I agree. API to me is a layer of abstraction that masks complexity. This could be as simple as a "Class" in my opinion.
But some devs see API mostly as a series network calls.
The browser provides an API, This comes in the form of the
documentAPI which provides thequerySelectorapi which happens to be the empty set ().A
setbeing a closer definition of mathematics, it does not define a quality, "In mathematics, the empty set is the unique set having no elements"In my opinion API is a public contract between creator of a class, component or library and consumer. For example simple domain object with a lot of properties can has API as a public method. It encapsulate private properties with this methods which increases the security of correct use of this class.
And we can replace class here with component or library. API is just a gateway.
I'm glad we're having an healthy discussion here.
love it