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