What an API Is: A Door With Rules Written On It
A program keeps its data inside. If the owner wants to share, they open a door and write rules on it: knock here, ask like this, show who you are. That door is an API. Knock the right way and you get an answer. Knock the wrong way and you get an error.
Every call answers four questions
- Where are you knocking? The URL, like /customers/42.
- What do you want? The method. GET reads, POST usually creates, PATCH changes part of it, DELETE removes.
- Who are you? Your API key or token, sent in a header.
- What comes back? Usually JSON: text with names and values that people and programs can both read.
See one for real
GitHub has a public API. This call reads the profile of octocat, GitHub’s example user. It is a GET, needs no key and changes nothing, so it is safe to try.
curl https://api.github.com/users/octocatcurl sends a request from the terminal. With no method given, it sends a GET. I ran this in Git Bash.
Where: api.github.com/users/octocat. What: GET. Who: nobody, the data is public. What came back: JSON, like "name": "The Octocat". Once you look for these four things, every API doc starts to look the same.
Do this in 60 secondsOpen https://api.github.com/users/octocat in your browser. Now replace octocat with your own GitHub username and see your profile as a program sees it.
Today’s AI angleWhen an AI agent "uses a tool", very often that tool is an API call like this one. The agent fills in the four answers and reads the JSON that comes back.