What’s an API Exactly?
Except when I do, I *never* get tired of the mix of abstraction and precision required to write computer programs.
IMO, programming is loaded with a lot of terms that get thrown around willy nilly, regardless of the audience’s level of expertise. If, with childlike naïveté you ask, what is that thing, the answer is often something unhelpfully broad. Back during my bootcamp I asked someone “what’s an API exactly?” and I believe the answer I got back was something like “everything’s an API.” Hmmmm. Can’t put my finger on it, but I feel like that answer is missing something.
During that same time I heard the term “API” used almost interchangeably with “backend” when creating a full stack application. I also saw it in the context of dealing with a library like React when I was building my own React application. And again in the context of integrating a 3rd party application into one’s own app, such as the Google Maps API, or the Yelp API.
I didn’t feel much incongruity between the first (backend) and last (external) usages, but the middle (library within one’s app) undermined my sense that I understood the term, since it destroyed the stabilizing sense that an API is something external to my application that must be fetched.
In reviewing some React docs just now I came across a reference to this that once again strikes me with its seemingly abstract specificity, and I dive in.
I google: “what is a library’s api”
Google’s first/top answer reads:
“API stands for Application Programming Interface. … As the name insinuates, and API specifies how a developer interacts with hidden methods and classes in a library or application. An API is a collection of software protocols that a developer can access through contract or agreement.”
“An API can be thought of as the logical representation of what is in the library, or the consistent format that explains what a developer can do with the library.”
“It is the part of the code that is accessible to programmers. The main difference is that the library refers to the code itself, while API refers to the interface.” — RapidAPI: API vs Library (What’s the Difference?)
To make this more applicable, let’s bring this back to the React docs. The summary at the top is basically all I need to get it (for now):
“React is the entry point to the React library…If you use ES6 with npm, you can write import React from ‘react’. If you use ES5 with npm, you can write var React = require(‘react’).” — React Top-Level API (if this quote looks confusing to you, click the link so you can see it with highlighting)
While this is simple, it’s a nice aha moment for me to realize that I have a clearer, less verbose way of explaining why every React component I write needs to start with this stupid-looking line of code:
import React from ‘react’
‘react’ is the library; React, the variable we assign that library to, becomes the API. (If part of this is wrong someone please correct me for the love of Spongebob.)
Anything React has to do to make our code work only works properly if the React variable is present in that file as this sort of import statement (or as a global variable if you want to be like that) because React is the entry point into the library, it is the (AP) interface.
No JSX will work if React isn’t there because “Each JSX element is just syntactic sugar for calling React.createElement()” (Creating React Elements) and after Babel converts JSX to plain JS that utilizes React.createElement calls, which would be equivalent to undefined.createElement() if we forget to import React! (Why do you need to import React in functional components?)
So back to my initial quandaries; have I answered my own questions?
I feel that the issue of an API feeling like it should be an external thing has washed away. I can now just conceptualize of the API as a point of contact between two worlds of code.
I’d call it a doorway, but I think that metaphor is misleading: a doorway in intuitive/physical/human terms we think about not as the door but really as the absence of material that one can walk through, connecting two rooms together. An API really is an interface; an object connecting two other objects. The problem is that there aren’t highly intuitive interfaces that we as humans regularly interact with to form metaphors from. I mean, a bridge I guess, but does that really feel right? Not abstract or poetic enough.
We could talk about GUIs and that’s not bad, but then we’re also using one technical term to explain another. Not ideal IMO.
My best thought at the moment is the depiction of the wormhole in Interstellar: this weird spherical shimmering visual distortion in the middle of outer space that connects distant galaxies, essentially separate worlds, to each other.
It’s not a doorway that one simply walks through (Sean Bean), it’s more of a ladder, an object that translates between one world and another, that connects, bridges. It has physicality to it, in the way a hole or empty doorway doesn’t: it’s an interface, whose physical properties, not the absence of physical properties, facilitate a two way transfer of information.
Another question/problem that irked me actually just resolves to an issue of ambiguous language: React is a library, and libraries are not applications, but React has an “application programming interface.”
Here is one explanation, though I find it a bit opaque:
“The word “application” used as an adjective is not restricted to the “of or pertaining to application software” meaning. For example, concepts such as application programming interface (API), application server, application virtualization, application lifecycle management and portable application apply to all computer programs alike, not just application software’ ( Wikipedia-Application Software > Metonymy).
This is a bit wordy, so I’ll just try to clarify here: application is being used as an adjective. It’s not saying the thing with the API is itself an application. I’m not entirely sure why this horrifically misleading phrasing is used, I feel like application here is just referring in an almost general, dare I say, layman’s way, to the fact that we’re in “rootie tootie smarty party programmy land,” as if “programming interface” didn’t get that message across clearly enough. Though I do enjoy saying “API;” sounds much smarter than saying “PI.”
Anyway, I think just omitting the “A” from API and thinking about it as just a “programming interface” makes more sense, since things like React, which is a library, and is not application software, can still have an API. Libraries and applications are both pieces of software/programming, so it doesn’t feel wrong at all to say that they have programming interfaces.