An API is an Application Programming Interface, which is essentially a way for software to communicate with other software over the internet. APIs are used to provide reusable and robust functionality to many different applications.
Apps on your phone and websites in your browser are both powered by data being sent over the internet. This happens using a simple relationship called client-server. The client requests data from the server, and the server is responsible for providing it. For example, the weather app on your phone is a client that interacts with a server that offers the data it shows you. At a high level, this process looks something like the following:
- You open the app and enter your location.
- The app uses the internet to contact a server that holds weather data and asks for the weather at your location.
- The server sends your app the weather details that the client asked for.
- The app shows you the weather data in a nice interface.
An API allows steps 2 and 3 to happen; the app client utilizes the server’s API to request weather data for a particular location.
URL stands for Uniform Resource Locator and is nothing more than an address on the internet. When you access www.google.com, your browser resolves that URL to a specific location where the Google server resides. Typically URLs are made up of two parts: a host and a path. Usually, the host is the company or product name, while the path indicates a specific offering. Consider the examples of https://twitter.com/home and https://twitter.com/notifications. In both, twitter is the hostname but /home brings you to your home page while /notifications brings you to your notifications page.
APIs are referenced using a specific URL (more on this later).
Communication Through Contracts
A contract defines every API – basically a definition of how the API can and should be used. There are a few main components here, so let’s walk through how this might work for our weather API:
Location – where can the API be accessed? This is a specific URL that the API can be found at. Let’s say our weather API is available at www.mycoolweatherapi.com/api.
Request – what do I need to provide/input to the API to get what I want? Let’s say our weather API accepts a single parameter called location name that allows you to obtain data for a specific location on the current date.
Response – what data/output can I get back from the API? Let’s say our weather API can provide temperature and chance of rain. This means that users of our API can expect to receive both of those data points for whatever location name they query for.
Putting this all together gives us our entire API contract: If you make a request to www.mycoolweatherapi.com/api and provide a locationName, then you can expect to receive the temperature and chance of rain on the current date for whatever location you requested. You can think of an API like a mathematical function; you can expect to receive some output back based on some input.
Usages of APIs
APIs are potent tools. They allow developers to build complex applications that utilize existing functionality without re-inventing the wheel. For example, anyone who wants to build an application that displays weather to a user without our weather API would have to figure out how to maintain their weather data. By providing this API, we are abstracting away the complexity of weather so that clients only have to understand the contract itself rather than the underlying process or data.
APIs also provide a programmatic way of obtaining data. You can manually google the weather in your city every day somewhat quickly, but imagine you had a spreadsheet of 10000 locations you needed weather for; you couldn’t handle that scale by yourself. A weather API would allow you to build software that can process those 10000 locations in a split second.
Consider some more examples of popular APIs and how they can be used:
- Airlines like Delta have APIs that provide data about their flight offerings (origin, destination, price, etc.). This is how travel sites like Kayak and Expedia aggregate and show you flights from tons of different airlines. They don’t need to know how Delta works on the inside; they need to use the Delta API to get the data they show to their users.
- Google has an API for accessing user information. When you see a website give you the option to “sign in with Google” (or Facebook, etc.), the API is how they are doing that.
- Credit card companies have APIs that allow merchants to charge customers. When you input your credit card information on a site like Amazon, they use your credit card company’s API to charge you for your purchase.
- Geocoding APIs allow you to provide an address and get a latitude/longitude back.
HTTP stands for HyperText Transfer Protocol and is a system for handling the client-server relationships discussed above. It prescribes how clients and servers are supposed to communicate over the internet and includes things like:
- Method types (GET, POST, etc.) to represent possible actions
- Headers to represent metadata about the request/response
- Status codes to represent whether or not a request succeeded. Two of the most common ones are 200 (success) and 500 (server error).
- Parameters to pass data to a server (such as API inputs).
Authentication and Authorization
Authentication is the process of verifying a client’s identity, while authorization is verifying a client’s permissions. Many APIs use both of these to implement security features. This is commonly done by asking clients to provide a unique identifier called a token when hitting an API that lets the API know who they are. For example, imagine you have an API for your eCommerce site – authentication and authorization allow you to ensure that your users can only view their orders and payment methods and not others.
JSON can also encode more complex nested objects like the following: