What Is an API? How APIs Work, with a Real Example for Beginners

Beginners ask our team the same question all the time: "Everyone keeps saying API. It's in every tutorial and every job post. What actually is it? I've never seen one." Our usual answer isn't a definition. It's "Go call one yourself." A line like "an API is a middleman that lets programs talk to each other" is easy to nod along to, and still leaves you with nothing to picture when you actually need to use one.

So in this article Superdev Academy will have you send a request to a real API, read the response that comes back, and then take it apart piece by piece: endpoint, method, status code, JSON and API key. You don't need to install anything, and you don't need to know how to program yet. The shortest possible answer is that an API (Application Programming Interface) is an agreement about how one program can ask another for data or ask it to do something, but that sentence makes far more sense once you've made a call yourself.

Call your first API with just a browser or a terminal

We'll use the GitHub REST API. GitHub lets anyone read public user data from it without signing up. We'll ask for the account called octocat, the sample account GitHub uses throughout its own documentation.

Option 1, the browser: paste this address into the address bar and press Enter.

https://api.github.com/users/octocat

Option 2, curl in a terminal: curl is a command-line program for sending requests over the web. It comes with macOS and most Linux systems, and according to the curl project every installation of Windows 10 and Windows 11 has it too. If you're in Windows PowerShell and the output looks strange, type curl.exe instead of curl.

curl -i https://api.github.com/users/octocat

The -i flag tells curl to show the response headers as well. Almost immediately you'll see something like this (we've cut it down):

HTTP/2 200
content-type: application/json; charset=utf-8
x-ratelimit-limit: 60

{
  "login": "octocat",
  "id": 583231,
  "name": "The Octocat",
  "company": "@github",
  "location": "San Francisco",
  "created_at": "2011-01-25T18:44:36Z"
}

If you see something like that, you've just used an API. Some values may differ from what we saw on the day we wrote this (28 September 2026), because this is live data the account owner can edit. The shape of the response stays the same.

What just happened in that one command

Two things happened. Your machine sent a request out to GitHub's server, the computer that serves the data, and the server sent a response back. Both travelled over HTTP, the same protocol your browser uses to load every web page.

The difference from opening a normal web page is who the reader is. A web page sends HTML for the browser to draw into something a person can look at. An API sends raw, structured data for a program to use. That's why all you see is text in curly braces, with no buttons and no images.

Put simply, an API (Application Programming Interface) is an agreement about how one program can ask another program for data or ask it to do something: what to send, and what comes back. GitHub has written its agreement down as documentation, and anyone who follows it can make the call.

You don't need to know what language GitHub's server is written in or where it keeps its data. You only need to know how to ask. That is the whole reason APIs exist.

An endpoint is the address of the data you want

The address https://api.github.com/users/octocat has two halves. https://api.github.com is the base URL, the street address of the whole API. /users/octocat is the path, which says which piece of data you want at that address. Put a path together with the method you use and you have an endpoint.

In GitHub's "Get a user" documentation this endpoint is written as GET /users/{username}. The curly braces mark a slot you fill in yourself. Swap octocat for your own GitHub username, or a friend's, and send the request again: the data that comes back changes to match.

Reading API documentation is something developers do almost every day. Good docs tell you which endpoints exist, what to send, and what the response looks like.

The method says what you want to do with the data

The request we sent used the GET method, which means "read this, don't change anything". Browsers and curl both use GET by default, so we didn't have to type it. Written out in full, our request was GET /users/octocat.

MDN lists every HTTP method on one page. These are the five a beginner meets most:

• GET: read data

• POST: send new data to be created, such as a sign-up or a new comment

• PUT: replace existing data with what you send

• PATCH: change part of existing data

• DELETE: remove data

The same path can behave differently depending on the method, which is why API documentation always pairs the method with the path.

The status code tells you first whether it worked

Look back at the first line of the response: HTTP/2 200. That 200 is the status code, and its full name is 200 OK. The request succeeded, and the data follows below.

Now try a username that doesn't exist:

curl -i https://api.github.com/users/this-user-should-not-exist-zzqq9

This time the first line says 404, meaning the thing you asked for wasn't found. That number is the first thing a program should check before it uses any data. What each code means, and what to fix when you see one, is covered in our separate article on how to read HTTP status codes.

JSON is a data format programs read easily

The data inside the curly braces is JSON (JavaScript Object Notation). The content-type: application/json header already told you that before the body arrived. Reading it takes four rules:

• Data comes in key and value pairs separated by a colon, such as "login": "octocat"

• A value in quotation marks is text (a string), such as "The Octocat"

• A value without quotation marks is a number or a special value, such as 583231, true, false and null (no value)

• Pairs are separated by commas, and the whole thing is wrapped in curly braces

Despite the name, JSON isn't tied to JavaScript. JavaScript, Python and Go all ship with built-in tools for reading it. Once your program has this response, it just pulls out the name value and puts it on screen, the same way plenty of apps show a user's GitHub name and avatar.

If you want to get fluent at reading JSON, we cover it in a separate article: What Is JSON? A Beginner's Guide to Reading JSON Files and Data.

An API key is your pass when the API needs to know who's calling

Notice that we never sent a password or key, and still got data back. GitHub allows anonymous requests for public data, with a ceiling. The x-ratelimit-limit: 60 line in the response says so, and GitHub's rate limit documentation states that unauthenticated requests are limited to 60 per hour.

Many real-world APIs, such as AI services, maps or payments, have you sign up and give you an API key, an identifier you attach to every request. It lets the provider know who is calling, bill the right account and enforce usage limits. That makes an API key as valuable as a password. How to store one safely and keep it off GitHub is covered in our article on API keys and .env files.

Where APIs hide in the apps you use every day

Once the request and response picture clicks, you start seeing APIs behind a lot of what you already use.

• A weather app doesn't measure the temperature itself. It sends a request to a weather data provider's API and draws the JSON it gets back onto the screen.

• A "Sign in with Google" button is one site calling Google's API to confirm who you are.

• A shop's mobile app and website show the same products because both call the same backend API.

• The AI chatbots embedded in many websites pass your message on to an AI model provider's API.

For a programmer, this means you don't build everything yourself. Need a map, call a maps API. Need to take payments, call a payment provider's API. A large share of development work is connecting several APIs into one working system.

Types of API: REST, GraphQL, gRPC and library APIs

To be complete: what we tried is a REST-style web API that talks over HTTP and answers in JSON. It's a common kind, but it isn't the only kind.

In the broad sense, an API is any interface one program exposes for other programs to use. The functions in a library you import into your code are an API too. Web APIs also come in other styles, such as GraphQL, which lets the caller choose exactly which fields to get back, or gRPC, used for communication between backend services.

So whenever you meet an API at work, ask three follow-up questions: what kind of API is it, does it need authentication, and how many calls are you allowed? The API's own documentation answers all three. No guessing required.

Two more terms people often ask us to compare with APIs are webhooks and MCP.

Where to go from here

If curl worked for you, here are three next steps, from easiest to hardest:

1. Change the path to try another GitHub endpoint, such as /users/octocat/repos, which returns that account's list of repositories, and practise reading JSON that comes back as a list.

2. Call the same API from code, for example with fetch in JavaScript, and show the name value on a web page.

3. Build an API of your own. To see what the server side looks like, read JS2GO EP.12: Creating an API with Node.js and Go or Go and RESTful APIs.

If you're not sure what to learn first, Learning to Code in the Age of AI: Which Skills to Focus On First is a good companion read.

Summary: what an API is, in one curl command

An API is an agreement that lets one program ask another for data or for work. What you just did was send GET /users/octocat to GitHub and get 200 OK back, with JSON containing the name The Octocat. Every piece you need is in that one command: the endpoint is the address, the method is what you want to do, the status code is the outcome, JSON is the data, and an API key is your pass when the provider needs to know who is calling.

No explanation of APIs lands as clearly as sending one request yourself. Change the username, change the path, make it answer 404 on purpose, and read what comes back. You'll understand APIs far better than you would by memorising a definition.

Follow more articles and tips for people starting out as programmers on our channels.

Facebook: Superdev School (Superdev) — https://www.facebook.com/superdev.school.th

Instagram: superdevschool — https://www.instagram.com/superdevschool/

TikTok: superdevschool — https://www.tiktok.com/@superdevschool

Website: www.superdevacademy.com — https://www.superdevacademy.com/