What Is an API? Everything Beginners Need to Know (No Tech Background Required)

[intro]

Simple API Example

You don't need a website or an app to use an API. You can use an API directly from your computer's terminal (Command Prompt, PowerShell, or Mac Terminal) using a tool called cURL.

cURL is an application that's automatically installed on most computers. You can check and see if your computer has cURL by running:

1curl -V

Note: on Windows you may have to run curl.exe for it to work properly.

You should see something like this:

1curl 8.18.0 (Windows) libcurl/8.18.0 Schannel zlib/1.3.1 WinIDN WinLDAP
2...

If you get an error, you can try downloading curl instead.

cURL API Request Example

1curl https://v2.jokeapi.dev/joke/Programming?safe-mode

When you run this command in your terminal, you're telling your computer to send a request to a server on the internet and print the response.

If everything works, you should see something like this:

1{
2    "error": false,
3    "category": "Programming",
4    "type": "single",
5    "joke": "There are only 10 kinds of people in this world: those who know binary and those who don't.",
6    "flags": {
7        "nsfw": false,
8        "religious": false,
9        "political": false,
10        "racist": false,
11        "sexist": false,
12        "explicit": false
13    },
14    "id": 22,
15    "safe": true,
16    "lang": "en"
17}

You just made an API request!

What Happens When You Call an API?

Let's slow down a bit and break this apart so we can learn how an API works.

First, curl is a command-line tool. It stands for "Client URL." Its job is simple: send a request to a URL and show you the response.

When you type the command above, your computer sends a request to the URL to send back whatever is at that address.

Looking at the URL itself, the base URL is https://v2.jokeapi.dev/joke/. This is the foundation of the API. Think of it like the main entrance to a building.

After the base URL, we added Programming. Now the full path becomes https://v2.jokeapi.dev/joke/Programming.

That extra word tells the API what category of joke we want. In this case, we're asking specifically for a joke about programming.

Many APIs work like this. You change part of the URL to change what data you receive. Then we added this at the end:

?safe-mode

That part is called a query parameter. The question mark ? tells the API that everything after the ? is additional instructions.

safe-mode is an option we're turning on. It filters out jokes that might be inappropriate.

Looking at the response, we see that it's in JSON format. JSON is a popular way to structure data, especially with APIs.

Let's break apart the data returned and see what the API returned:

• "error": false: No errors; that's a good thing!
• "category": "Programming": The category of the joke
• "type": "single": The joke's a one liner. Sometimes the API returns the setup + punchline separately.
• "joke": "...": The actual joke
• "flags": { "nsfw": false, "religious": false, ... }: The flags a joke has. adding safe-mode ensures these are all false.
• "id": 22: Unique ID of the joke
• "safe": true: Confirms we used safe-mode
• "lang": "en": Language joke is in

That's it! No magic or mystery. We simply sent an API request to a server and it responded with this structured data.

If you want to learn about how I figured out what all the data meant, you can take a look at the documentation for this API yourself: Joke API Docs. Most APIs will have documentation that tells you how to use the API and interpret the data it returns.

How to Send Data to APIs

Now that you have a foundational understanding on what an API is, we can dive into how you can send data to an API.

API Keys

To learn about API keys, we will use he APIs on this site.

First you have to sign in or create an account on our accounts page. After you sign up, check your email and click the magic link sent from marsthelimit.com to verify your account.

Now go to your dashboard and go to the "API & Keys" tab. At the top, you should see your secret key.

That key is how your app proves it's allowed to use the API. Think of it like a password for your application. Without it, the server won't respond.

Once you have that key, you're ready to start using the APIs.

Simple Calculator API

The APIs on this site require that you have enough tokens to use. Each request will use one token.

There's a test API that I included on my site that users can practice sending requests to without using any tokens.

Here's an example cURL request

1curl https://api.marsthelimit.com/calculate/add \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer YOUR_API_KEY" \
4  -d '{ "num-1": 2, "num-2": 2 }' \

Note: the backslashes ('') at the end of the lines tells your terminal you're using multiple lines. On Windows, you need to replace the '' with '^'

This is a real curl API request example using your API key. If you've never made an API call before, this is exactly what it looks like in the real world.

Let's break it down into simple pieces.

Line 1: The Endpoint

1curl https://api.marsthelimit.com/calculate/add

This is the API endpoint, as we discussed earlier. You are telling the server to run the code at the specific URL.

The First -H (Header)

1-H "Content-Type: application/json"

The -H means "header." With APIs, headers act as shipping labels. They tell the server what data type we send, our authorization, etc.

This specific header, Content-Type, tells the server what kind of data you're sending. In this case, we're sending JSON. This is what you will use for all APIs on this website and for most other APIs.

The Second -H (Authorization Header)

-H "Authorization: Bearer YOUR_API_KEY"

This is the API authentication for this website. Be sure to replace YOUR_API_KEY with your actual key.

Your API key proves you're allowed to use the API. It works like a password for your application. Without it, the server rejects the request.

The -d (Data You're Sending)

1-d '{ "num-1": 2, "num-2": 2 }'

This is the request body. In this JSON object, we send two numbers to the API.

You send:

1{ "num-1": 2, "num-2": 2 }

The server responds with:

1{
2  "result": 4
3}

Experiment

Now try to change up some things. See what happens when you only send one of the numbers or if you try to send "num1" instead of "num-1".

You'll quickly learn how to send JSON data to APIs by making mistakes and trying things out for yourself.

Conclusion

You started this article now knowing how APIs work, but now you've actually used one. You made a real request, sent JSON data, authenticated with an API key, and received a structured response. That's not theory. That's how APIs work: a client sends a request to an endpoint (a function over the internet), the server processes it, and returns JSON.

If this makes sense, you're no longer just reading a beginner API guide; you're thinking like someone who understands how APIs connect applications. If you want to use a more complicated but more useful API, I encourage you to try out our Engineering Calculator API. This API saves time by helping you out with engineering formulas such as Faraday's Law and Ohm's Law.