Thanks to a society infatuated with quick wins and instant gratification, the IT
industry has radically transformed from that of a decade ago. All possible thanks
to more open and permissive business models and accessible networking infrastructure. The software industry has more or less done away with packaged DVDs and moved
entirely to electronic software distribution. This means that you can visit a
vendor’s site, decide if you like the product and within minutes have downloaded the
software and enjoy it on your device.
Software-as-a-Service takes this one level further where the software is already
available via the Cloud and typically all that is required of the user is to think of a
password of sufficient strength to create an account.
But what about APIs? Sure, with the SaaS model, one could quickly access an
API but (un)fortunately most of us don’t fluently speak HTTP and JSON. This
means we’re stuck writing a piece of software to interact with the API before
we can realistically see how it works and explore all that it has to offer. That, or you need to seek out your local curl or wget ninja for some of the gnarliest command lines that you’ve seen in a while.
Enter API Explorers. There are a variety of formats and approaches for API Explorers but the
goal is to make APIs just as accessible as something like SaaS. That is, within
minutes a user can go from nothing to interacting with an API and examining the output
of live calls. This model of interaction is particularly attractive for those who
prefer to learn by doing. It also gives a convenient “ground truth” to check when there
are discrepancies in human provided documentation.
Today API Explorers are most commonly integrated with the API’s documentation
although sometimes, if the offering is very API specific, it might be displayed prominently in a landing page. In both cases the idea is to give a user the
ability to bounce between reading about the API and then going and seeing how
it really behaves.
The amount of effort required to publish an API to an API Explorer continues to
decrease. API specifications like Swagger come with tooling to automatically
generate an API Explorer like the following:
Even better, there are a number of modern software development platforms
(like Loopback) that make it hard to NOT have an API Explorer. By default, a
new Loopback project will provide the developer with an API Explorer that
documents all of the REST endpoints for their application.
And if you’re “blessed” with a legacy situation, there is always the ability to derive
the Swagger from the existing traffic patterns as discussed in the
Inferring web API descriptions from usage data post.
This makes for a slick way to iteratively build up an explorer to help understand what type
of endpoints exist in your system and what payloads they expect.
API Explorers are certainly a great advancement for the effective consumption of APIs and hold an important role in the API tooling ecosystem. However, there are right ways (and not so right ways) to use them which will be discussed in the next post.
Curious what AlchemyAPI Relation Extraction found in this post?