An API, or Application Programming Interface, acts as a bridge for allows technology products and services to communicate with each other across the interne through a set of definitions and protocols.
There are many types of APIs, ranging from private internal APIs that never leave a company, to Open API's that can be accessed by the public for free or for a subscription cost. We will be working with hypothetical API's and Open API's for real companies during this blog.
An API is called through a URL, which at the most basic, breaks down into:
1) a base
2) an endpoint
3) parameters
One way to think about this is through a grocery store analogy.
1) The base is the grocery store as a whole. It has food, many brands of food, which is stored in aisles.
2) The endpoint is like the aisle or section of the grocery store you're looking in. You can go to the produce section, the frozen aisle, the beverage section, prepared foods, etc..
3) Parameters define what specifically you are looking for. Once you are in the frozen aisle, you can define if you're looking for ice cream, and a specific brand or flavor of ice cream.
For instance, a fake api base that doesn't exist for a grocery store could be:
https://api.grocery.com
Sometimes, the api may have a version number, so it might look more like:
https://api.grocery.com/v4
This would all be considered part of the base.
Next, you would specify the endpoint. Let's say our grocery store has just 5 sections: produce, frozen, beverage, prepared foods, and canned foods.
If we want to look for ice cream, we would look in the frozen foods section, so we're now building out our URL to look like this:
https://api.grocery.com/v4/frozen
Next, you want to find all instances of ice cream, in your favorite flavor, vanilla. These are your parameters.
In our hypothetical grocery store, ice cream is a 'food' and flavors are defined by 'type.' So now we've built a call into:
https://api.grocery.com/v4/frozen?food=icecream&type=vanilla
Note: there is always a "?" separating endpoints from parameters, and an "&" separating parameters from each other.
The above example is made up. But real companies follow this format, and have outlined their base url, endpoints, and available parameters through extensive documentation of their APIs. It is important to read through this documentation to ensure your requests run smoothly.
You can see examples below:
The documentation is where you will find information about the base URL, endpoints, and parameters.
For instance, in Spotify, they call out their base URL in plain English.
This means that when calling the Spotify api, the URL always begins with https://api.spotify.com.
Spotify's API is quite complex, with 14 different possible endpoints (such as albums, artists, and shows), and requires authorizations. But it's still a cool example to explore!