What is an API?

What is an API? How does it make cloud possible? And why does it matter at all?

Let's start our exploration of API with something much simpler: your local coffee shop.

The Coffee Shop

You wake in the morning, start your day, head to work, and stop at your local coffee shop for your daily fix. You wait on line (hopefully not too long), and when you get to the barista - your regular, Susan, is working this morning - you ask for a "medium decaf skim latte, extra hot".

Fortunately, Susan, knows exactly what you are asking for. She takes the order, puts it in her system, then takes your card for payment.

You wait a few minutes, someone calls out your name, you take it and head to the office (or back home, if you work remotely), and enjoy the start of your day.

What just happened, other than you having an enjoyable start to your day? How did it work that you were able to efficiently communicate exactly what you wanted, and Susan was able to provide precisely that, while you paid for precisely what you ordered?

The Interface

You and Susan have agreed, even implicitly, on an "interface", a way to describe orders of drinks, how to prepare them, how to pay for them, and how to receive them. This interface includes:

• A way to describe the desired size. If you asked for small or large, it would have been fine, but if you asked for "ultra-small-medium", or "dribbat" size, she would not know how to help you.
• A way to describe the selected drink, a latte. If you had asked for tea or hot chocolate, it would have been fine, but if you asked for a "whiskey sour" or "vampire's blood", she would have refused.
• Understood modifiers, such as "decaf" and "skim". If you had asked for "extra shot", that would have been fine, while "with a golf ball" is not on their menu, and "laced with arsenic" definitely gets that psychiatric services call.

We can keep going, but the idea is clear. You and the barista have an agreed set of things you can ask for, descriptors and modifiers, and how the process will work.

it looks like something free-form and simple like this:

This entire "contract" between the two of you is your "interface". You might not think of it in those formal terms, but the coffee chain most certainly does. It thinks about every step of the process, every item on the menu, how the lines will work, how the order process flows, and everything else that occurs in the store.

It is as if Susan has a big sign over her head saying, "here is what you have to say to order, and it better be on this list, or we will not be able to process it."

Of course, this whole interface applies to ordering coffee, and specifically coffee at this specific coffee shop, or at most others in the same chain. If you used the exact same terms and processes to order food at a sit-down restaurant, or airline tickets from Etihad, the results would be a disaster.

The Application Interface

This "interface" works for a very specific purpose. You can apply it only to that purpose, unless someone else agrees to use the exact same one and copies it. Your "application" of this "interface" is what makes the whole process possible. You have an "application interface" to ordering coffee at this shop.

All of this is really important, and what makes almost every economic interaction work.

Fortunately, we are humans with flexible language, so you don't always need to know it precisely in advance. Imagine you walk into a new coffee shop, one that looks different than you ever have seen before. You have that human intelligence, and can look for places where a menu might be, or can ask someone who ordered already where it is, or what options are available. You might even ask the barista (who may be called a "coffee-specialist" at this store). Eventually, you learn the "interface" for this "application" (new coffee shop) and use it.

It probably would slow things down, as anyone who has been stuck in line behind a family who didn't know what they want to order, or has never gone through airport security and doesn't know to take their laptop out of their bag and phone out of their pocket, can attest!

Having laid the groundwork, let's move back into the world of technology. We will, however, take one more step before moving to the cloud.

The Application Programming Interface

Instead of ordering coffee via your local barista, human-to-human, you want to order it via an app.

The app on your iPhone or Android may be shiny and friendly, but it exists only on your phone. Once you pick your order - "medium decaf skim latte" - it has to transmit all of that to the coffee chain's systems across the Internet. Those systems do not have human intelligence and flexibility. They need to be fast and efficient. They need to be programmed for precise behaviour: send this message in this format to order a "latte", modify it this precise way to add "skim" and "decaf", etc. If you said to the barista, "I want it with skin milk", she will understand you meant "skim milk". To a computer, "skin" and "skim" are completely different words. "Skin milk" isn't anywhere in the system (we hope).

The application interface between you and the barista is the menu and agreed language. The application between the app on your phone and the coffee shop's systems is a much more precise one, created for programming interactions. It is not just an "application interface", of which there can be many, but an "application programming interface", or, if we take the acronym, an API.

The API let's you use the interface for a specific application in a programmatic fashion. Specifically, it lets you "program" the interface. You can give it commands, and it responds.

That API is pretty much identical to the one you used with your barista. It just isn't human-to-human, but program-to-program.

You might not realize it, but you use APIs all day, every day.

• When you order a coffee on app, the coffee shop API is what lets the app talk to the coffee shop systems.
• When you read the Twitter/X feed, their API is what lets your Twitter/X app log in as you and then retrieve the latest tweets for your timeline.
• When you send an email, the Gmail or Outlook API is what lets your mail app send the email properly.
• When you connect to a WiFi network, the WiFi API is what lets your phone find the network and join it, making network services available to you.
• When your pilot checks the weather out via an app from the National Oceanic and Atmospheric Administration's National Weather Service, it is using an API to get the weather data.
• Your accountant, or tax program or service, like Intuit, uses the Internal Revenue Service API to submit tax returns for your business.

None of these activities, not a single one, could work without an agreed API. If Twitter did not publish a well-defined API, there would be no way for any app, even their own, to connect to it and send out or read tweets.

If you go to Google right now, and search for any technology service you use - Salesforce, Equinix Metal, AWS, GitHub, Starbucks, Google Maps, United Airlines, TSA - along with the word "API", you likely will find a well-published one.

For an API to work, it needs three things:

• First, the owner of the service must provide a well-defined and well-published API specification.
• Second, their service must implement the API. Surprisingly, plenty of companies have published API specifications, but not quite gotten around to actually implementing them in their services.
• Third, applications must use that API, or "consume" it.

What does an API look like?

APIs usually have a few components:

• An endpoint. This is an address on the network where you can access it. Some services have multiple endpoints, for example, the production one may be at https://api.example.com while the testing sandbox may be at https://sandbox.example.com. Or a company might have multiple production endpoints, separated by region, e.g. https://us.example.com and https://eu.example.com.
• A base path. This is a "prefix" that comes before all of the other specific parts. Often this contains a version, e.g. /api/v2/. This is not a requirement, but many APIs do have them.
• A structured path. There are lots of ways to do this, and since this is not a guide to building your own API, we won't go into it too deeply. Usually, some form of the path represents the resources you are after. For example /orders or /users.
• Body. What should you put into the request. Is the format json, or protbufs, or xml, or something else?
• Actions. How to take an action. It isn't enough to know you want to deal with orders; you need to know how to distinguish between "place a new order" and "check the status of an order" or "list all orders". These usually either are a property of how the request is submitted, known as http verbs like POST or GET, or part of the path.
• Authentication & Authorization. Description of how you authenticate to the service, and how you use that authentication to enable your requests.

Constructing an example, these might be some paths for your coffee shop chain:

• order a new coffee: POST https://api.coffeecool.com/api/v2/orders?coffee=latte
• check the status of an order: POST https://api.coffeecool.com/api/v2/orders/12345

There are lots of great resources on the Web to learn how APIs work and how to construct them. There also is an enormous amount of debate about what the "right way" is to build an Internet-facing API. There are some obvious dos and dont's, but most of it is almost religious debate.

The Equinix Metal API documentation is available here.

How Do APIs Make Cloud Possible

One the key elements of cloud is the ability to provision resources programmatically, no humans involved. How did we get the basic resource, a server, before the cloud?

1. Arrange the capital expenditure (capex) budget and get it approved
2. Place an order for a server
3. Reserve a location in the data centre: building, cage, rack, location
4. Receive the server
5. Place an order for someone to install it at the reserved location
6. Place an order for someone to wire it up: power, network, keyboard/mouse

While the "place an order" phases might have been in a computerized order-tracking system, all the rest of it involves scheduling people. This is a long and expensive process.

Cloud provides it all on-demand. Sure, you can reserve some resources and get fairly large discounts for doing so, but the actual provisioning process is fully automated. Use the Web console or one of many software clients, e.g. metal CLI, run a few commands, and your server is ready in minutes or less.

All of the above stages (except for capex budgeting; for that, or ongoing operational expenditure, or "opex", you are on your own!) now are fully automated and immediate.

This only works because of two things:

1. Cloud providers put in an enormous amount of work to automate that provisioning process, including auditing and billing.
2. Cloud providers define an API specification for provisioning those servers, publish that spec, and implement it on their service, so you can consume it.

Even with all of the automation, you need APIs to use that cloud. APIs make the cloud possible for you.