Distinguish the parts of an API call

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 will create new data (like profiles and events) in your Klaviyo account. Other methods you may see in Klaviyo are PATCH (updating pre-existing data) and DELETE (deleting a pre-existing data).

When you asked the server for the lunch menu, they knew exactly where to find it, because the restaurant has a designated spot for storing them.

While the method determines how you interact with the data, the request URL specifies where you interact with the 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

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 API endpoint. All Klaviyo API endpoints start with https://a.klaviyo.com/.

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.

Now, imagine the Klaviyo Cafe also serves breakfast and drinks, each with separate menus. This distinction between similar types of resources can be handled by adding more detail to our request URL. Just as you told the server you specifically want a food menu, during lunchtime, we would add that information to our API call through the use of query and path parameters.

The request URL we just defined for asking for a lunch menu was

https://a.klaviyocafe.com/api/menus/food

As part of this URL, food specifies that you are looking for a menu in the food section, as opposed to a drinks menu.

In order to specify that you want a lunch menu specifically, you can add a query parameter at the end of the URL after the question mark:

https://a.klaviyocafe.com/api/menus/food?mealtime=lunch

This provides you with a menu that is filtered down to only include the lunch options.

Some API calls require path parameters. Path parameters 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 after a question mark. If you have multiple query parameters, connect them with an ampersand (&).

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.

After perusing the lunch menu, you decide on a delicious cheeseburger. Inevitably, your server will ask you what type of cheese you want and what side dish to include.

This information would make up the body of an API call. The body of an API call, often referred to as a payload, 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 need to contain all the required information that makes up a profile, such as the person's name, email, or phone number.

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 metadata about your request. 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 you are actually authorized to do whatever it is you are requesting, whether that is accessing a specific Klaviyo account or ordering a glass of wine.

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.