Public APIs and API integration for Platform User Design

API as abstraction layer
When it comes to software, APIs are literally everywhere. APIs go hand in hand with one of the most fundamental concepts in computer science: abstraction. Abstraction is just a way of organizing the complexity of a system so that complicated actions can be handled in a simple way. Think of this abstraction like those Amazon Dash Buttons, the battery operated, push-button circuit boards you can use to order staples from Amazon. This is what they look like:

A few examples of Amazon Dash buttons. Order more detergent or paper towels at the press of a button.
You order a Dash Button from Amazon and use an app on your smartphone to associate it with your Wi-Fi network, your Amazon account, and a product, say, your favorite brand of paper towels. Then, whenever you want to order more paper towels, you just press the button. The Dash Button connects to the Internet and sends a message to place an order on your account. A few days later, paper towels arrive at your doorstep.

Like an API, the Dash Button is a blissfully simple interface that hides all kinds of complexity behind the scenes. The ID of the product you ordered must be retrieved from some database. Your delivery address must be pulled from your account. The nearest fulfillment center stocking your paper towels must be determined, then notified to remove an item from the available stock and package it up. Finally, the package must be routed through some combination of airplanes, trucks, and vans along with other packages in a way that ensures that all the packages will reach their destinations efficiently.

Now imagine you had to coordinate all of these things as a customer. You’d never order paper towels because it’s too complicated and time consuming and you have better things to do. Luckily, the whole ordeal is abstracted away from you. There is a long, interconnected chain of computer systems and human processes that make those paper towels show up at your doorstep, but all you have to think about is pressing a button.

This is what APIs are like for programmers. They take an overwhelming amount of complexity and define a relatively simple set of interactions that you can utilize instead of doing it all yourself. In any software project, you’re likely using tens if not hundreds of APIs directly, and each of those APIs relies on other APIs and so on.

Public APIs and API integration
APIs are a longstanding concept in computer programming, and they have been part of developers’ toolsets for years. Traditionally, APIs were used to connect code components running on the same machine. With the rise of ubiquitous networking, more and more public APIs, sometimes called open APIs, have become available. Public APIs are outward facing and accessible over the Internet, allowing you to write code that interacts with other vendors’ code online; this process is known as API integration.

These kinds of code mashups allow users to mix and match functionality from different vendors on their own systems. For instance, if you use the marketing automation software Marketo, you can sync your data there with Salesforce CRM functionality.

“Open” or “public” should not be interpreted as meaning “free of charge” in this context. You still need to be a Marketo and Salesforce customer for this to work. But the availability of these APIs makes integration a much simpler process than it otherwise would be. (InfoWorld has a great list of public APIs you should know about.)

Web services and APIs
You might recall the term web services from the early ’00s and think that the idea of an open API sounds pretty similar. In fact, a web service is a specific kind of open API, one that meets a fairly rigid set of specifications, including that they be specified in Web Services Description Language (WSDL), an XML variant.

Web services were meant to be used as part of a service-oriented architecture (SOA). As the Nordic APIs blog explains, that gave web services something of a bad name, as SOAs never quite lived up to their potential. Advances in the techniques used for service-to-service communications—notably lighter, more flexible REST—have also left web services somewhat behind in the world of public APIs.

REST APIs
Web services were originally designed to communicate using SOAP (Simple Object Access Protocol), a messaging protocol that sends XML documents over HTTP. Today, however, most web-based APIs use REST—Representational State Transfer—as an architectural style.

REST was formally introduced by Roy Fielding in his doctoral dissertation in 2000. It’s a set of architectural components, design principles, and interactions used for building distributed systems that involve media of any kind (text, video, etc.). At its core, REST is a style of building systems that allows for flexible communication and display of information across the web while providing structure necessary to easily build general purpose components.

In a REST API, a resource could be pretty much anything, but examples include a user, a list of tweets, and the current results of a search for tweets. Each of these resources is addressable at a resource identifier, which in the case of web-based REST APIs is usually a URL, such as https://api.twitter.com/1.1/users/show?screen_name=twitterdev. When an application requests a resource using the identifier, the API delivers the current representation of that resource to the application in a format that the application can consume, such as a JPEG image, HTML page, or JSON.

One of the big differentiators of REST is that it involves sending data to the requesting application. While this provides great flexibility, allowing the application to do whatever it wants with the data, it comes at the cost of efficiency. Sending data over the web for processing is quite slow compared to doing the processing where the data resides and then sending the results.

Of course, the problem with the “efficient” approach is that systems hosting the data would need to know what applications want to do with it ahead of time. Thus, in order to build an API that has general purpose usability and flexibility, REST is the way to go.

API examples
There are plenty of public APIs out there for you to interact with, many from industry behemoths. The ability to access some platform company’s code programmatically via an API is what makes them a platform, in essence. Some prominent API examples include:

Google APIs, which allow you to connect your code to the whole range of Google services, from Maps to Translate. APIs are so important to Google that they acquired Apigee, a leading API management platform.
Facebook APIs, which allow you to programmatically access Facebook’s social graph and marketing tools. (The company has been restricting just what user data you can access via these APIs in the fallout from Cambridge Analytica and other scandals.)
To really get a sense of how APIs work, let’s do a deep dive into two: the Java API, which Java developers use to interact with the Java platform, and the Twitter API, a public API that you would use to interact with the social networking service.

The Java API
The Java API is a library of software components available “out of the box” to anyone who has installed the Java Development Kit. These components implement common tasks and generally increase productivity because programmers don’t have to start from scratch every time. One of the basic components used in software is something called a List, which, as you might expect, keeps track of a list of items. The Java API defines what you can do with a List: add items, sort the list, determine if an item is in the list, etc. It also specifies how to perform those actions. In order to sort the List, you need to specify how you want the List sorted: alphabetically, numerically descending, brightest to dullest color, etc.

The API doesn’t have to explain what happens inside the engine when you put your foot on the accelerator. That’s why, if you learned to drive a car with an internal combustion engine, you can get behind the wheel of an electric car without having to learn a whole new set of skills. The what and how information come together in the API definition, which is abstract and separate from the car itself.

One thing to keep in mind is that the name of some APIs is often used to refer to both the specification of the interactions and to the actual software component you interact with. The phrase “Twitter API,” for example, not only refers to the set of rules for programmatically interacting with Twitter, but is generally understood to mean the thing you interact with, as in “We’re doing analysis on the tweets we got from the Twitter API.”