The last post took a look at the current state of interactively exploring APIs.
This post is going to dig a little deeper into when that makes sense to use a
traditional API Explorer and what alternatives exist when it doesn’t make sense.
API Explorers provide a near instantaneous way to interact with a web API. It
enables a developer to get a quick feel for the endpoints the API exposes and the
data input and output. The data aspect is the key complication for the practicality
Why do I say this? APIs are intended for programatic access, and API Explorers
do a very nice job of making a human consumable interface for interacting with
the APIs. However, the data piece can be significantly more complicated to
“wrap” for humans. APIs that perform some type of processing typically accept
payloads that computers appreciate (JSON, XML, url-form-encode). People appreciate these
formats much less. Constructing a complicated payload moves the user outside the
API Explorer and into other tools to try and define a set of data that will conform
to the required inout schema and include the right data elements for the experiment at hand.
For complicated APIs this is very tedious and error prone (although does make for
some good testing!).
The other aspect besides data is the chaining of API calls. That is, for a
payment API, I would want to query a customer, check their subscriptions and if
not already subscripted create a new subscription and charge. Chaining together
these calls is not so simple when working with independent Explorer forms. The
user must manually parse the output of one call and then feed that in the correct
form into the input of the next call. In the sequence above it is highly unlikely
that somebody is going to see it through end-to-end. Subsequently, showing the
same flow to another interested individual takes equally as much time.
So, considering the problems with complex data and chaining what can be done to
help? The answer, I suggest, is to focus on delivering interactive “notebook”
type environments where developers can “code” their experiments. This enables the
power of the programming language and libraries to do the grunt work between the
actual API calls. A company like Stripe does a fantastic job of this as their
documentation is written exclusively to take advantage of their language specific
SDKs. As a developer, I pop open an interactive ruby shell, load their library and
start exploring. Not to mention Stripe includes reasonable values for objects that
already exist in your data set (i.e. want to query a user? here is an example call
that will actually query a user in your account).
API Explorers are clearly very valuable from a documentation perspective and can
be very helpful when interacting with APIs offering predominantly independent
endpoints and simple data constructs. As the payloads become more complicated and
the call chaining more involved, language specific exploration offers clear benefits.
What type of API do you offer? Are you presenting the right way to interact with your
API? Let us know what you think.
Curious what AlchemyAPI Sentiment Analysis found in this post?