APIs for the rest of us

Understanding what APIs are, let alone actually using and getting value out of them, is usually a topic reserved for engineers or otherwise technical people. But that doesn’t need to be true! This guide will walk through everything you need to get started, from a technical foundation down to debugging common errors.

Like a database , each API has its own specifics and quirks; no guide is going to cover them all. But use this as a jumping off point, ask engineers when you have questions, and you’ll be golden.

What’s an API exactly?

Applications are just a bunch of functions that get things done: APIs wrap those functions in easy to use interfaces so you can work with them without being an expert. Let’s start with an example. If you’re an e-commerce company, there are a bunch of things you need to get done internally that power your site:

• Show available items and sizes
• Create orders
• Update an email address

All of these tasks are completed through a bunch of code behind the scenes – adding rows to a database, generating and shipping orders, and updating data, in our case. Companies build APIs on top of these complex workflows so that actually using them is as simple as a few lines of code. Sometimes, an API is just a really simple way to select rows from a database; other times, it can encapsulate thousands of lines of hairy code.

Generally, there are two types of APIs you’ll come across: internal APIs and public APIs. Your company will have APIs for internal operations (like our e-commerce example) – those aren’t available to the public, obviously. They drive business operations. But sometimes, companies with interesting datasets will release public APIs so that developers can build cool stuff on top of their data. A good example is the Twitter API, which lets people like you interact with tweet data programmatically. Even the government has public APIs.

A third type of API that’s a bit harder to classify (and getting more popular!) is the vendor API. Companies like Stripe sell a product that’s basically an API: you use their interface to implement payments into your app. Products like this usually come with some sort of admin panel or frontend to manage the data you’ve put into them too. These APIs aren’t quite available in the open, but they aren’t built by you either, so they’re neither public nor internal.

Common API implementations: SOAP, REST, gRPC

Regardless of what type of API you’re dealing with (internal, public, vendor) there are three major protocols / technologies that developers use to build APIs: SOAP, REST, and gRPC (yes, obviously they all need to be acronyms). Interacting with each of them brings its own challenges, formats, and tools.

1. SOAP

SOAP (Simple Object Access Protocol) is the oldest of the API protocols: it was originally released in 1998 (!) by a few Microsoft engineers. It’s based on XML, which sort of looks like HTML. Here’s an example of what kind of code you’d need to write to work with it:

<?xml version="1.0"?>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="http://www.example.org">
  <soap:Header>

</soap:Header>

  <soap:Body>

<m:GetStockPrice>
      <m:StockName>T</m:StockName>

</m:GetStockPrice>

  </soap:Body>

</soap:Envelope>

If you’re thinking this looks...awful, you’re not alone. SOAP has all but fallen out of favor, and is generally considered a legacy or enterprise (scary word) kind of technology.