Despite what you hear in the tech press, there is no single way to deliver Application Programming Interfaces (APIs). In reality, there are a wealth of tools to choose from, and depending on the job, you will need a combination of different tools to successfully deliver a usable API — this paper looks to walk you through this modern API toolbox. full version: https://streamdata.io/resource-library/modern-api-toolbox/

1. White Paper
A Modern API Toolbox
http://streamdata.io
Prepared by:
Kin Lane
API Evangelist
New York, NY
kin.lane@streamdata.io

2. When it comes to developing web APIs REST is the
dominant design pattern out there, and is a philosophy
that has enjoyed a significant amount of the spotlight
over the last decade, but in reality on the ground at
companies, organizations, institutions, and government
agencies of all shapes and sizes, there is a much more
robust API toolbox being used to get the job done.
The toolbox that has emerged isn’t just about what
is needed to equip an API architect to build out the
perfect utopian API-driven IT vision of the future. It is
a toolbox that is equipped to get us from present day
into the future, acknowledging all of the technical debt
that exists within most organizations, and that we are all
desperately looking to evolve our infrastructure as part
of a larger, ongoing digital transformation. Encouraging
us to realize a toolbox that is increasingly about pushing
the boundaries of what has been historically defined as
an API, and continuing to transform how we deliver
APIs, ensuring we are ready for what we will see on the
ground within real world organizations.
Application Programming Interface (API)
API is an acronym standing for applicationprogramming
interface. A term that you should not allow to limit
the scope of applications to just be about web or
mobile applications, or even to the growing number of
device-based applications emerging on the landscape.
Applications are all about applying digital resources
which are made available via an programmatic interface.
Despite what you hear in the tech press, there is no single way to deliver Application Programming Interfaces (APIs).
In reality, there are a wealth of tools to choose from, and depending on the job, you will need a combination of
different tools to successfully deliver a usable API -- this paper looks to walk you through this modern API toolbox.
Taking the data, content, media, and algorithms being
made available and applying them anywhere they
are needed on the web, within mobile and device
applications, or on the desktop, via spreadsheets, digital
signage, or anywhere else that is relevant, and sensible
in today’s digital world. The API mindshare has been
co-opted and led by many storytellers out of the startup
space, looking to direct funding, build markets, but
this world is often times at odds with what actually is
occurring on the ground within organizations.
API does not mean REST. This is simply the legacy
from over a decade of technologists trying to steer
the direction of technology for ideological benefit.
It is an unproductive legacy of the API sector, and
one we should all work to move beyond. Application
programming interfaces aren’t the solution to every
digital problem we face. They are about understanding
a variety of protocols, messaging formats, and are about
finding the best path forward depending on how you are
applying the digital resources you possess. A modern
API toolbox should reflect a holistic view of the API
landscape, something that has significantly evolved over
the last decade, and is something that will continue to
evolve, and be defined by what is occuring on the ground
within the companies, organizations, institutions, and
government agencies who are
putting APIs to work across
their operations.
SOAP Web Services
During the early years of the
web, there was a significant
amount of investment into
thinking about how we
exchanged data across many
industries, as well as within
individual companies. The web was new, but we did
the hard work to understand how we could accomplish
data interoperability in a machine readable way, with
an heavy emphasis on the messages that we were
exchanging. Looking back we probably could have
spent more time thinking about how we should using the
web as a transport in all of this, as well as the influence
of industry and investment interests were having, but
A Modern API Toolbox

3. the web was still very new. We did not fully understand
the many ways in which the web would be put to use
to drive every business sector, and begin to impact so
much of how our society would work.
While web services provided a good foundation for
delivering application programming interfaces, it
underinvested in its usage of the web as a transport,
and became a victim of the commercial success of
the web. The need to deliver web applications more
efficiently, and a desire to hastily use the low cost web
as a transport, quickly bastardized and cannibalized web
services, into a variety of experiments and approaches
that would get the job done with a lot less overhead
and friction. Introducing efficiencies along the way,
but also fragmenting our enterprise toolbox in a way
which we are still putting back together today. SOAP
Web Services are still present in 2018, driving many
enterprise solutions, and while they may not be the
preferred choice for newer, more green field projects,
they are still very much a fact of life on the ground for
many IT groups who are making business work on a
day to day basis.
XML & JSON Remote Procedure Calls (RPC)
One of the more
fractious aspects
of the web API
evolution has been
the pushback when API providers call their XML or
JSON remote procedure call (RPC) APIs RESTful,
RESTish, or other mixing of philosophy and ideology,
which has proven to be a dogma stimulating endeavor.
Diehard REST believers prefer that API providers
properly define their approach, while many RPC
providers could care less about labels, and are looking
to just get the job done. Making XML and JSON RPC a
very viable approach to doing APIs, something that still
persists almost 20 years later. Finding success, as the
acronym suggests, making remote procedure calls using
low cost web technology.
Amazon Web Services, Flickr, Slack, and other RPC
APIs are doing just fine when it comes to getting the
job done, despite the frustration, ranting, and shaming
by portions of the API community. It isn’t an ideal
approach to delivering programmatic interfaces using
the web, but it reflects its programming roots, and gets
the job done using low cost web infrastructure, while
still reaching a large audience. RPC leaves a lot of room
for improvement, but is a tool that has to remain in the
toolbox. Not because there will be many new RPC APIs
to publish, but there is no doubt that at some point we
will all have to be integrating with an RPC API to do
what you need to get work done delivering and evolving
an existing systems and applications.
REST As A Centerpiece
Roy Fielding’s dissertation on representational state
transfer, often referred to as simply REST, is a very
important piece of work. It makes a lot of sense,
providing one one of the most thorough looks at how
to use the web for making data, content, media, and
algorithms accessible in a machine readable way. Many
folks feel it is the RIGHT WAY to do things, and one
of the reasons it is the default approach for many API
designers and architects. However, REST is just a
philosophy, and much like microservices, provides us
with a framework to think about how we put our API
toolbox to work, but it isn’t something that should blind
us from the other tools we have within our reach. REST
gives us an important lens to look at our digital resources
through, but shouldn’t prevent us from stepping back
and thinking beyond everything as just being a resource.
REST is where most API conversations will begin,
but it doesn’t entirely encompass what is meant when
you wield the term API. REST provides an excellent
base for thinking about how we deliver APIs, but can
begin slow our effectiveness when we leave your REST
blinders on, and let dogma control the scope of our
toolboxes. REST has demonstrated the importance of
the web when talking about APIs, and will continue to
drive how we deliver APIs for many years. It has shown
us how to structure, standardize, and simplify the
delivery of APIs, and helped our applications reach as
wide as possible audience, using commonly understood
infrastructure. REST is the centerpiece of our web API
toolbox, providing us with a common way to think about
our digital resources, and how we might want to provide
access to them in a structured, consistent, and widely
known way. While REST has a number of limitations, it
reflects how simplicity in design can become one of the
most important aspects of how we apply the tools we
have in our toolbox.
Allowing For The Negotiating Of CSV Data
The spreadsheet is king when it comes to getting
business done on the desktop, and the web. The ubiquity
of the spreadsheet is partly due to the portability of the
comma separated value (CSV) format, which allows
complex spreadsheets to be distilled
down, and shared via email and the
web. Many developers and database
folks prefer a lot more structure than
the CSV or spreadsheet brings to the
table, but the concept of allowing for
the negotiation of CSV responses
from APIs can move mountains
when it comes to helping onboard
business users, and decision makers to the potential of
APIs--even if the data format doesn’t represent the full
potential of an API. CSV responses are about setting a
low bar for the complexity of our APIs, making them
accessible to a very wide business audience, delivering
digital resources beyond just developer and IT groups.