As the old saying goes, the devil is in the details! Before diving into the deep, if you're landing on this specific blog, note there are a few other blogs that lead up to this blog. You can catch up here:
These blogs were a direct result of a VMUG presentation I delivered last year and I received a lot of kudos about my explanation of APIs to non-developer/infrastructure type folks.
As a consumer of online services and user of apps, you're using APIs all the time (you might not know it). Let's look at online banking (I was going to use a social media example, however not everyone is using social media). Every interaction with an API runs through the following steps:
A request or query is made.
A program or task runs based upon the request/query.
The application sends back a response from the API endpoint.
I used to hear "API call" a lot when I started supporting customers in this software defined world, so I started reading a lot online to make sense of what that actually meant. There's a specific way an API call is built to get the right data from the API endpoint.
Here's a simplified breakdown that I walked folks through during my VMUG presentation last year:
So, there's a base URL, a query, and an API key. Note that the query is everything after the ? and the API key is everything after the &. What does this actually look like though?
Simple Start
Next, let's start to unpack the anatomy a bit. Suppose we have the following API endpoint (all examples in this blog post will be hypothetical):
https://api.example.com/users/{user_id}
Here, {user_id} is a placeholder for the actual user ID you want to retrieve information for. To make an API call, you would use an HTTP client (e.g., cURL, Postman, Axios in JavaScript, or the requests library in Python). In the following example, we'll use cURL, a command-line tool for making HTTP requests.
Let's say we want to get information about the user with ID 333. The API call would look like this:
curl -X GET https://api.example.com/users/333When you execute this command, cURL will send an HTTP GET request (I'll cover HTTP methods in the next blog post) to the API endpoint. The API server will process the request, look for the user with ID 333 in its database, and then respond with the relevant user information in a structured format like JSON:
{
"user_id": 333,
"name": "Shannon Kuehn",
"email": "[email protected]"
"age": "43"
"city": "Elmwood Park"
"state": "Illinois"
}
Simple API Example + API Key
Now what about an API call with an API key? The process is similar and varies ever so slightly. For example, you'd need to first obtain an API key. What is an API key? An API key is a unique identifier used to authenticate and control access to an API. The key acts as a secret token that you include in your API requests to prove your identity and overall permissions on the API endpoint.
In this example, let's assume the API key is "YOUR_API_KEY". Let's also assume you want to get the weather for New York City.
Using cURL, the API call would look like this:
curl -X GET "https://api.weatherprovider.com/currentweather?city=New%20York&apikey=YOUR_API_KEY"For simplicity's sake, here's the breakdown of the API call:
`-X GET` specifies the HTTP method as GET, indicating that we want to retrieve data (again, this will be the next blog post).
`"https://api.weatherprovider.com/currentweather"` is the base URL of the API endpoint that provides the current weather data.
`city=New%20York` is a query parameter specifying the city for which we want to get the weather. Note that spaces are URL-encoded as %20. Additionally, the query parameter comes after the question mark (?) in the API call.
`apikey=YOUR_API_KEY` is the query parameter that includes your API key, allowing the API to identify and authenticate your request. The ampersand (&) links the query and the API call together in the URL.
Lastly, the entire URL (base, query, and API key) is joined together by quotation marks in the cURL example above. In a cURL command, the quotation marks help encapsulate the entire URL (including parameters and the API key) as a single argument to be passed to the cURL command-line tool. This is important because some characters in the URL, such as question marks (?), ampersands (&), or equal signs (=), have special meanings in the command-line interface and the shell. By using quotation marks, you prevent the shell from interpreting these characters prematurely and ensure that the entire URL is treated as a single unit.
Upon making the API call in this fictitious example, you would receive a response from the weather API containing the current weather information for New York. Please note that this is a simplified example. Real-world API calls might have more query parameters and/or other authentication mechanisms. The good rule of thumb is to refer to the API documentation provided by the service for accurate and complete usage instructions.
Simple API Example + Parameters
What about parameters? In the context of an API call using an HTTP method, a parameter refers to a piece of information that you include in the request to provide additional details or instructions to the server. Parameters are essential for customizing the behavior of the API and specifying the data you want to interact with or retrieve.
HTTP methods, such as GET, POST, PUT, DELETE, etc. (again - I'll cover these in the next post), are used to define the type of operation you want to perform on the server's resources. Parameters, on the other hand, are used to pass specific data to the API in a structured way.
There are several ways to include parameters in an API call, depending on the HTTP method used:
GET Method - In a GET request, parameters are typically included in the URL's query string. As I stated earlier, the query string starts after the question mark (?) in the URL and consists of key-value pairs separated by ampersands (&). For example:
GET https://api.example.com/users?name=Shannon&age=43POST Method - In a POST request, parameters are included in the request body, often in JSON or form-encoded format. The data is typically sent as part of the request body, and the content type header specifies the format being used. For example:
POST https://api.example.com/users
Content-Type: application/json
{
"name": "Shannon",
"age": 43
}PUT Method and DELETE Method - Similar to the POST method, parameters for PUT and DELETE requests are usually sent in the request body as well, using JSON or form-encoded format.
The actual parameters you need to include and their formats depend on the specific API you are working with. API documentation provided by the service will outline the available parameters, names, acceptable data types, and any additional requirements.
That takes us to the end of this post. The purpose of this blog was to take you through API details. The next blog will focus on the HTTP Methods (as they're important to understand). Once I go through the HTTP Methods, I'll take you through a few real-life examples using Postman! So, stay tuned!