If you’re not a developer, but you work in tech, the term API is probably something you understand in a conversational sense. You likely know what it stands for (application programming interface), and perhaps your teams use APIs to do their job—or maybe it’s even the product itself (Twilio SendGrid, for example).
But what exactly is an API and how do they work?
Understanding the deeper principles behind APIs will help you better market, sell, or use these technologies yourself.
This post explains how APIs work, how developers build them, and how to use them (with real-world examples).
How web browsers interact with servers is a fundamental principle of APIs. The web is a collection of remote servers dispersed across the planet. When you open up a browser and type in a website, the browser is making a call to the client’s server (whatever application or server that a website is hosted on) to fetch and display whatever lives on that URL.
While an API is not the server itself, it is the part of the server, known as the endpoint, that sends and receives certain responses. APIs are a way for different pieces of software to communicate (aka sending and receiving) with each other by opening endpoints.
Developers set up API calls to retrieve specific data needed for various purposes when they are building applications or websites. For example:
Did you just open your Instagram app? That was made possible by an API call.
Have you ever added an event to your Google Calendar from another website or email? That site was leveraging the Google Calendar API to grab that specific information from the Google Calendar server.
Takeaway: Developers set up API calls to retrieve specific data types to display what they need when a user is on a website or running an application.
Another term that you’ve likely heard is REST API. It’s not different per-say than the traditional definition of an API. Still it’s worth understanding why REST APIs have become so popular and what distinguishes REST APIs from others.
In the beginning, APIs were built to meet the requirements of SOAP (Simple Object Access Protocol). But this method was a bit tedious and required lots of bandwidth to transfer data sets. It also demanded a lot of developer energy (like not the fun kind). SOAP uses the notoriously heavy XML markup language to display data. Useful for ensuring universal compatibility–but that’s about it.
Developers were looking for lighter and more flexible ways to make API calls. REST (representational state transfer) APIs provide an alternative solution to SOAP API. They are not constrained by a specific protocol, although they must meet certain architectural styles (if you’re interested in diving into that, head over here).
Instead of being displayed with XML markup, the server uses the lightweight JSON language (just text files) instead. REST APIs are far lighter in bandwidth than SOAP—they’re typically only a URL—and they are naturally optimized for communication on the web.
Takeaway: Think of REST APIs as the Marie Kondo of data. They take and use only *precisely* what they need. SOAP APIs are like your neighbor’s garage that is currently filled to the brim with toilet paper.
Regardless of what protocol or styles an API follows, there are several types of APIs including:
Open APIs - Also known as public APIs, these endpoints are accessible by any developer and typically don’t impose any restrictions on the user. They typically accept donations.
Partner APIs - These are APIs that are designed to be used together and typically can only be accessed by some sort of marketplace.
Internal APIs - These are internal tools that companies use to help their employees be more efficient or provide a more secure way for employees to share data/information.
Composite APIs - Composite APIs are a way to consolidate APIs calls that are related but would normally require individual API calls.
There are loads of APIs out in the wild (some count upwards of 15,000) that help users access diverse applications. Below are a few notable ones that will help you understand the scope of the API ecosystem.
Let’s say that you own a local liquor store, and you want to provide cocktail recipes on your website. You could consider using the Cocktail DB API above. All that data (the cocktail recipes) already exists on someone else’s server and can be assessed via the API.
When a user clicks on the margarita recipes (arguably the superior cocktail), their servers find that specific recipe sends it out in JSON, it gets picked up the website and parsed into HTML and CSS to be presentable on your website browser.
Adding a weather section to your website is a super common use case. Think of any ski resort, bike shops, or tour company. The OpenWeatherMap API stores all the weather forecasts and information and displays only the portion that you are requesting.
This API provides both free and premium versions depending on how much data you want to display.
The SendGrid Email API leverages SMTP (simple mail transfer protocol) to allow customers to send large amounts of transactional and triggered emails–think password resets, account confirmation, and shipping notifications.
The Twilio SMS API is another REST API that provides a way to add messaging features to applications. SMS messaging has become increasingly popular as a way for brands to communicate with customers because it’s personal, in real-time, and these messages are read at much higher rates.
Read the documentation. Any API should have applicable documentation for you to follow. It’ll tell you what dependencies you have, what type of API it is, and how to use it. Poor documentation should be a red flag for you and your developer. We’re pretty proud of Twilio’s and SendGrid’s superb documentation.
Generate an API key. You’ll need to generate an API key to start using it. Here are instructions from the Google Maps API:
Note: Never share API keys and ensure that they are not visible on any public code you put on GitHub.
The rest is up to you! The opportunities are truly endless when you’re working with APIs. For a look at all the opportunities to work with the Twilio API, check out the Twilio Code Exchange.
If you’re interested in using the SendGrid Email API to send free email, check it out here.
