Understanding APIs for Automation

I use APIs and the HTTP node/module quite a lot in automations.

I've been working with APIs for over 13 years now both building and calling APIs. So I'm pretty comfortable with using the HTTP node to call any API. Actually it is way easier to use no code tools like n8n to call APIs than coding it.

This episode of Bot & Beyond is for people starting with automations without prior technical background to be able to understand APIs and how to use the API documentation to effectively to call any API.

So What is an API?

API stands for Application Programming Interface.

I'll use the very popular restaurant analogy explain what it is!

• Imagine you’re at a restaurant. You sit at your table, look at the menu, and decide what you want to eat.

• You tell the waiter your order, and they take it to the kitchen.

• The kitchen prepares your meal, and the waiter brings it back to you.

• In this scenario, the waiter is like an API. - An API is a messenger that takes your request, delivers it to a system , and then brings the response back to you.

• The menu is like the API documentation.

An API allows different software systems to talk to each other.

For example, when you use a weather app on your phone, the app doesn’t have all the weather data itself. Instead, it uses an API to ask a weather service for the information, and the API delivers the data back to the app so you can see it.

There are different kinds of APIs

• REST APIs (Representational State Transfer) – Uses HTTP methods like GET, POST, PUT, DELETE.

• SOAP APIs (Simple Object Access Protocol) – Uses XML messages for communication.

• GraphQL APIs – Fetches precise data using queries instead of predefined endpoints.

• Webhooks – Event-driven APIs that send data when an event occurs.

In Automations we mostly use REST APIs and Webhooks.

In Make or N8N, when you use a node/module like the Google sheets, Email or LinkedIn, it is calling the corresponding API underneath. The platform(make or n8n) just made things easy for us by creating a node. Otherwise we'll have to send a request using the HTTP node to the API.

HTTP Requests

Whether you call a REST API or a Webhook, you are basically sending an HTTP request.

Let's look at what an HTTP request is made of.

HTTP Methods

This is like the type of action you’re asking the it to perform.

URL (Uniform Resource Locator)

This is like the address of the restaurant and the specific item you’re ordering. For example:

• The URL https://restaurant.com/menu is like saying, "I want to see the menu at this restaurant."

• The URL https://restaurant.com/order/123 is like saying, "I want to check the status of my order number 123."

Headers

These are like special instructions or notes you give to the waiter. For example:

• "I’m allergic to peanuts." (This could be a header like Allergy: Peanuts.)

• "I’d like my food spicy." (This could be a header like Preference: Spicy.)

• "I’m sending this request in English." (This could be a header like Content-Language: en.)

In APIs, headers often include information like:

• Authentication tokens (to prove you have access rights).

• Content type (to tell the server what kind of data you’re sending, like JSON or XML).

Body (Payload)

This is like the actual order you’re placing. For example:

• If you’re ordering a pizza, the body might include:

{
  "pizza": "Pepperoni",
  "size": "Large",
  "extras": ["Extra cheese", "Mushrooms"]
}

In APIs, the body is where you send data to the server, like when you’re creating a new account or updating your profile. Note: request body usually only applicable to POST, PUT, and PATCH requests.

Query Parameters

These are like extra details you add to your request. For example:

• "Can I see the vegetarian options on the menu?" (This could be a query parameter like ?category=vegetarian.)

• "Can I get my order to go?" (This could be a query parameter like ?takeout=true.)

In APIs, query parameters are often used to filter or customize the response. For example:

• https://restaurant.com/menu?category=pizza&sort=price means, "Show me the pizza items sorted by price."

Endpoint

This is the specific part of the API you’re interacting with, like a specific page on the menu. For example:

• /menu is the endpoint for viewing the menu.

• /order is the endpoint for placing an order.

Putting It All Together

Here’s an example of an HTTP request to place an order at a restaurant API:

POST https://restaurant.com/order
Headers:
- Authorization: Bearer your_membership_token
- Content-Type: application/json
Body:
{
  "item": "Pepperoni Pizza",
  "size": "Large",
  "extras": ["Extra cheese", "Mushrooms"]
}

This is like saying:

• POST: "I’d like to place an order."

• URL: "At this restaurant’s ordering system."

• Headers: "Here’s my membership token to prove I’m allowed to order, and I’m sending my order in JSON format."

• Body: "I’d like a large pepperoni pizza with extra cheese and mushrooms."

Authentication

Some APIs are public. Which means anyone can access the API without authentication. eg: REST Countries

Most APIs are protected by authentication. It is to make sure only authorized users or systems can access the API.

There are many different types of authentication, it's a topic by itself which I'll cover in a later time.

For now, let's look at the most common methods of Authentication.

• Passwords or API keys: Like showing your membership card.

• Tokens: Like getting a temporary wristband at a concert that proves you’re allowed to be there.

• OAuth: Like giving a friend permission to order food for you using your account, without sharing your password.

The API documentation will have the information you need on which authentication method it uses, how to get an API key or token, and also how to send it in your request.

API Documentation

When you want to use an API, you first have to look at their API documentation.

Think of the menu in the restaurant as the API documentation.

The menu tells you what you can order (the available options), how to ask for it (the format of your request), and what you’ll get in return (the response). For example, the menu might say, "If you order a cheeseburger, you’ll get a burger with cheese, lettuce, tomato, and fries on the side."

In the same way, API documentation is like a guide or instruction manual for developers. It explains:

• What the API can do (the available functions or services).

• How to ask for something (the format of the request).

• What you’ll get back (the response).

For example, if you’re using a weather API, the documentation might say, "If you send a request with a city name, the API will respond with the current temperature, humidity, and weather conditions for that city."

Following are some common terminology that you would come across in an API doc.

• Base URL: It is like the restaurant's address - it's where all requests start. eg: https://api.weatherservice.com/v1

• Authentication: This is like your reservation number - you need it to get service. eg: Authorization: Bearer YOUR_API_KEY

• Endpoints: These are like different menus - each one offers specific information:

  • The "current weather" endpoint is for right now - eg: Endpoint: /current

  • The "forecast" endpoint is for future weather - eg: Endpoint: /forecast

Rate Limits

Imagine the restaurant is very popular and gets super busy during lunch hour.

To make sure everyone gets served fairly and the kitchen doesn’t get overwhelmed, the restaurant might have a rule: Each table can only order 3 dishes every 15 minutes. 

This way, the kitchen can keep up with all the orders, and no single table hogs all the resources.

Rate limits work the same way.

APIs often have rules about how many requests you can make in a certain amount of time. For example, an API might say, "You can only make 100 requests per hour."

This ensures that the system (like the kitchen) doesn’t get overloaded and can serve everyone efficiently.

If you try to make too many requests too quickly (like ordering 10 dishes at once), the API might "slow you down" or even temporarily block you.

So, rate limits are like the restaurant’s rules to keep things running smoothly and fairly for everyone!

I started off thinking I would cover the HTTP node in n8n but this is already too long. I'll leave it for next time.

Have a great week!