What Are APIs

and why they matter even if you’re not a programmer.

alt_text

Do you pull the same reports every week to send to your superiors?

Do you pay an intern to enter data from one AP to another every week?

Does your organization have some custom process that you want to implement that your software doesn’t support by default?

If the answer to any of the above questions is yes, then you should care if the software your organization uses has an API.

What is an API

API stands for Application Programming Interface. Just like:

a GUI, Graphical User Interface, lets any user interact with the software graphically,

an API lets any application (computer program) interact with the software programmatically.

Example

For example, to find the current weather from openweathermap.org using the human-friendly user interface (GUI), you would enter the location in the search bar like so.

alt_text

Now suppose you wanted to automatically pull the weather data for every day and store it in a Google Spreadsheet. To do so, you’d hit the openweathermap.org API endpoint(a URL for APIs) like so:

http://api.openweathermap.org/data/2.5/weather?q=Austin&appid=439d4b804bc8187953eb36d2a8c26a02&units=imperial

And you’ll get the same weather data shown in the human-friendly GUI but in a computer-friendly format called JSON.

{
  "coord": {
    "lon": -97.74,
    "lat": 30.27
  },
  "weather": [
    {
      "id": 802,
      "main": "Clouds",
      "description": "scattered clouds",
      "icon": "03d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 83.34,
    "feels_like": 86.83,
    "temp_min": 81,
    "temp_max": 86,
    "pressure": 1020,
    "humidity": 66
  },
  "visibility": 10000,
  "wind": {
    "speed": 8.05,
    "deg": 360
  },
  "clouds": {
    "all": 40
  },
  "dt": 1600101504,
  "sys": {
    "type": 1,
    "id": 3344,
    "country": "US",
    "sunrise": 1600085716,
    "sunset": 1600130257
  },
  "timezone": -18000,
  "id": 4671654,
  "name": "Austin",
  "cod": 200
}

As you can imagine, it’s much easier to program a computer to simply hit the API endpoint than to train it to use the GUI. And while the JSON response is not designed to be easily read by humans, it is easy for computer programs to use.

Why you should care if you’re not a programmer

Okay, so APIs make it easier for computer programs to interact with software. But why should you care if you are not a computer programmer?

Well, if you want to automate routine tasks, integrate different software applications together, or customize a process that your software doesn’t allow by default, then it behooves you to select software that has a good API.

With a good API, you are much more likely to find off the shelf solutions to these problems or find consultants that can quickly and cheaply build them for you.

Uses

Automations

Google Analytics tracks how visitors interact with your website. With its GUI you can create a report of the top-visited pages of your website like so.

alt_text

You can even download it to a Google Sheet to share with your boss.

But what if you wanted to send this to your boss every week? This is one of those routine tasks that can get really annoying over time.

Because Google Analytics has a reporting API, a consultant, or even a tech-handy coworker could write a small program to automate this task.

Integrations

Now suppose you use Stripe to accept payments for your services online and you use Salesforce as your CRM.

By default, Salesforce doesn’t have a built-in Stripe integration. If neither had APIs, you might be stuck manually entering payments into your CRM (yuck).

However, because both Stripe and Salesforce have open, well-documented APIs, you have options for integrating the two services.

In fact, there are several off-the-shelf tools that do exactly this. No need to pay a developer to create it for you.

Of course, if those off-the-shelf solutions don’t work for you, you’ll still be able to pay a developer to program a custom solution for you.

Customization

Suppose however you wanted to implement some custom pricing that your payment provider doesn’t provide by default. For instance, say you charge clients for hours of consulting upfront but offer price breaks like so.

Hours Price per Hour
1-3 $50
4-10 $30
10+ $25

If you use a payment provider that doesn’t have an API, you may be stuck manually creating invoices and sending them to clients.

But if you’re using Stripe (which I recommend) you could pay any developer or Stripe consultant to create your custom pricing for you.

Stripe’s API is so good, you could even integrate it with a form on your website and allow clients to buy more hours without having to talk to you at all.

How to tell if an app has a good API

If your organization’s software has a good API, you can automate, integrate and customize much more cheaply and easily.

But, when selecting software, how can you tell that it has a good API?

Many software applications will claim to have an API, but, for a non-coder, it can be difficult to tell upfront if it’s a good API or not.

Here are a couple of heuristics you can use.

Documentation

First, look at the documentation for the application’s API. Even though you may not be able to interpret the documentation yourself, it’s usually pretty clear when an API is well documented.

Good documentation will be clear, well organized, with both code-level examples and qualitative descriptions of those examples. Often, a well-maintained API will support multiple coding languages, which you can see in the documentation.

Finally, world-class API documentation is interactive - you can actually test the examples with your data, right from the documentation.

For instance, Stripe’s documentation is famously good.

alt_text

Conversely, Evernote’s is infamously bad.

alt_text

The Stripe documentation is interactive and loaded with code-level examples in different languages with clear descriptions of the examples on a split-screen. The Evernote documentation is just a wall of text with little or no code-level examples.

Good documentation saves a developer a ton of time, which saves you money.

Webhooks

Pro-tip: if you need to integrate with the app in real-time, you need to make sure the app’s API has a webhook. A webhook is a specific type of API that fires an event immediately when something happens.

For instance, if you want to be emailed every time somebody makes a payment on your website, your payment provider needs to have a webhook that fires whenever a payment is made.

REST APIs

REST stands for REpresentational State Transfer. It’s a bit technical, but suffice it to say, most modern, well-maintained APIs are designed as REST API as opposed to Thrift or SOAP APIs.

Quickstart examples

Many well designed API’s have simple quick start examples that you can use without any programming experience yourself. Think about the openweathermap.org API example above.

Often times just getting up and running with the API is the hardest part of the whole project, so effective quickstart guides can save a lot of time.

Communities

The best APIs have large communities of developers that discuss issues and share projects on community forums.

A large community will help you or your developer find examples similar to your needs, saving you time and money.

Off-the-shelf third-party solutions

Finally, you should look for off-the-shelf solutions developed by third-party developers. For instance, Salesforce has an entire App store where developers share and sell add-ons built with its API.

As such, you may be able to find an off-the-shelf solution to your problem.

Conclusion

When selecting software for your organization, you doubtlessly consider how intuitive and user-friendly the GUI is. For analogous reasons, you should consider how computer-friendly the API is.

With a good API, you can replace repetitive user tasks with automated computer programs. Thus freeing the employees at your organization to do the creative things that only humans can do.

comments powered by Disqus