Why do you need to know about APIs?
Most modern products both use APIs and offer APIs to others.
- If you have a web UI, it uses APIs.
- If your system exchanges information with another, it uses APIs.
- If you’re building internal tools, APIs enable integrations between apps.
- If you’re building SaaS, customers will expect your APIs so they can build on top.
You don’t have to code them yourself.
But you do need to know how they work — otherwise, how can you design for customers and partners if you don’t understand the foundation?
APIs in simple words
API = Application Programming Interface.
Think of it as the language of applications.
APIs in alien language
Imagine Earth gets visited by friendly aliens.
They want to collaborate, trade, maybe share their advanced tech.
There’s just one problem — they don’t speak our language.
Not even hand gestures work.
So they hand us a guidebook of their language.
That guide is basically… an API.
It tells us:
- What words mean
- How to ask questions
- What answers to expect
That’s exactly what APIs do for systems. They’re the translation layer between two worlds.
REST APIs – Alien common phrases page
The first page of the alien guidebook is common phrases.
That’s REST APIs.
- REST uses simple, standard HTTP methods: GET, POST, PUT, DELETE.
- Every piece of data has its own address (a URL).
- Responses are usually neat and predictable (JSON).
- The rules are consistent across systems.
Examples:
GET /alien/technology → “Show us your tech.”PUT /alien/homeaddress → “Update alien homeaddress to Earth.”POST /alien/recipes → “Share human recipes with aliens.”DELETE /alien/cursewords → “Delete bad words from alien phrasebook.”
Want to test REST APIs in under 3 clicks and for free?
Try out a free Swagger Petstore UI — you can click “Try it out” and see how requests and responses work.
GraphQL – Alien custom translator headset
Now imagine instead of flipping through the guidebook, the aliens give you a translator headset.
You ask one custom question, and you get exactly what you asked for — no more, no less.
That’s GraphQL.
- One single endpoint instead of many URLs.
- You decide exactly which fields to return.
- No “overfetching” (too much data) or “underfetching” (not enough).
Examples:
- “Tell me alien recipes, but only names and spice levels.”
- “Now also include tech items invented in the last 100 years.”
Benefits: Flexible and efficient.
Challenges: Without limits, you can overload the system with massive queries.
Try it here in under 3 clicks and for free: Star Wars GraphQL API.
SOAP – Alien formal ceremonies
Finally, some aliens are very traditional.
They don’t like casual phrases or flexible headsets.
They insist on formal ceremonies with long scripts, where every word must be exactly right.
That’s SOAP.
- Uses XML and a WSDL document (the script).
- Strict, verbose, reliable.
- Common in banks, insurance, and government.
- Includes built-in error handling and security standards.
Example:
- “Perform the recipe-sharing ritual with full nutritional details, in the exact sequence required.”
Benefits: Very structured and safe.
Challenges: Slow to work with and overly complex compared to REST.
Want to see it? Download SoapUI and test a public SOAP service.
Advanced: Try Coding a REST API with AI
If you’re curious how APIs look under the hood, you can get AI to build one for you.
Copy-paste this prompt into ChatGPT (or your favorite AI tool):
Build a minimal REST API using Python + FastAPI.
Domain: Alien Recipes.
CRUD for recipes with fields: id, name, originPlanet, spiceLevel (1–5), ingredients (array of strings).
Requirements:
- Endpoints: GET /recipes, GET /recipes/{id}, POST /recipes, PUT /recipes/{id}, DELETE /recipes/{id}
- In-memory store (no DB needed)
- Validation with Pydantic
- Auto-generated docs at
/docs
- README with run instructions
- Example cURL commands
Run it locally in 3 steps:
pip install fastapi uvicorn- Save the code as
app.py
- Run:
uvicorn app:app --reload → open http://localhost:8000/docs
That’s it — you’ll see the alien “guidebook” turned into real code you can play with.
