Welcome to the Klaviyo Café
To understand what each component of an API call does, imagine you are dining at the Klaviyo Café. You sit down and order a meal off the menu. The server goes to the kitchen, places the order, and then returns with the meal you ordered. In this case, the server acts as a liaison (an API): a way for you (the user) to get a prepared meal from the café kitchen without having to get hired, put on an apron, and cook it yourself. You don't even need to know exactly how the food is prepared because the server provides a handy way for you to interact with the kitchen and get what you want.
An API works the same way, except instead of a meal, you receive data.
Making an API call is just like ordering off the menu. Once your order is placed (the request is sent), the API accesses the data you are looking for and returns a response (that delicious meal) exactly as you ordered.
APIs allow you to specify exactly what data you want to send and/or receive. There is a specific format that API calls, also referred to as API requests, follow.
Explore the parts of an API call
Read about the components of an API call and how they apply to both real APIs and the Klaviyo Café.
Method
As soon as you sit down at the Klaviyo Café, you ask your server for a menu, and they return with the menu you requested.
Once you have made your decision, you provide the server with the information they need to place the order: the item you want to order, the sides that come with it, and any modifications you'd like to make.
All API calls have an associated method that represents how you interact with the data. Asking the server for the menu is akin to a GET request, where you are trying to get some sort of information, whether it's a menu or some Klaviyo data.
When you are sending information into a system, like telling the server the details of your order, you are making a POST request. Making a POST request into Klaviyo sends the provided information into Klaviyo to create objects (like profiles and events) in your Klaviyo account. Other methods you may see in Klaviyo are PATCH (updating a piece of data) and DELETE (deleting a data object).
Request URL
When you asked the server for the lunch menu, they knew exactly where in the restaurant to go to get you that menu.
While the method determines how you interact with the data, the request URL specifies the location where you are sending or getting your data. URLs are unique locations for particular content, just like the lunch menu bin at the café is a specific location for lunch menus.
In this example, the request URL may look something like https://a.klaviyocafe.com/api/menus/food?mealtime=lunch
When you make a Klaviyo API call, you ask the API to go to a specific location represented by the request URL, also known as an endpoint. For instance, to create an event in Klaviyo, you need to send the API call to the URL associated with the events API: https://a.klaviyo.com/api/events/. To create a profile, you should instead direct the API call to the URL associated with profiles: https://a.klaviyo.com/api/profiles/. The request URL will always be listed in the documentation for the API call you are using. Request URLs are also known as API endpoints.
Query and path parameters
The Klaviyo Café has separate food and drink menus on different shelves. They also serve both breakfast and lunch.
The request URL we just defined for asking for a lunch menu was https://a.klaviyocafe.com/api/menus/food?mealtime=lunch.
As part of this URL, food specifies that you are looking for a menu in the food section, as opposed to a drinks menu. At the end of the URL, mealtime=lunch also provides you with a menu that is filtered down to only include the lunch options.
These are examples of path and query parameters. Path parameters are required in some API calls and make up part of the request URL that specifies the location the data exists, like the food menu shelf. Query parameters are optional parameters often used to sort or filter the data you are requesting. Query parameters are appended to the end of the request URL.
Note that query parameters will be added to the end of the URL after a question mark. If there are multiple query parameters, they will connected by the & symbol. You can read more about query parameters here.
You can use Klaviyo's API reference documentation to determine what query parameters (for operations like filtering and sorting) are available for the endpoint you are calling.
The difference between query and path parameters is quite subtle, so identifying which type of data should be which type of parameter can be tricky. In addition to the Klaviyo API reference documentation, you may be interested in this article that discusses the difference between query and path parameters.
Body
After perusing the lunch menu, you decide on a delicious burger. This order requires some extra information, though; you need to pick a side dish and provide the temperature at which you would like your burger cooked.
The body of the API call provides additional, necessary information about the request you are making. When using Klaviyo's APIs, you’ll find that POST requests require an API body that includes the information you’re sending. For instance, if you are creating a profile, the body will contain a profile data object with identifiers such as the profile's email or phone number as well as any additional properties like profile name and location.
Headers
In addition to your burger, let’s say you want to order a glass of wine. In the United States, this requires confirmation that you are legally allowed to order alcohol, so the server checks your ID. The ID acts as a request header.
Headers are used to provide additional information, or metadata. In Klaviyo, headers are used to authorize the API call and ensure that only permitted users can access your Klaviyo data. The authorization header is similar to the ID check in that it confirms that you are actually authorized to do whatever it is you are requesting to do, whether that is access a specific Klaviyo account or order a glass of wine.
Response
Finally, after sending an API call, you will always receive a response. After making a GET request, the response will contain the information you requested. For example, after asking for a lunch menu, the response is the lunch menu.
A response consists of a response code and a response body. The response code – also referred to as a status code – provides information about whether the request went through successfully or whether it encountered any errors. The response body contains either the information you requested or information about any errors.
You will see some examples of API responses and what they mean later on in this course.