DEV Community

Edwin Mwiti
Edwin Mwiti

Posted on

Fastest Way to Learn API's

**

LEARNING ABOUT APIs

**
REST APIs is like a ordering food to the waiter(API) you as the client using the menu(rules) to the restaurant(server).
Your weather app asking for the temperature to the server the API ensures you get this information by just getting the temp.

THE SIX CONSTRAINS

1.Client-Server.
You (the client) use the Amazon app to buy shoes.The Amazon server handles inventory, payments, and shipping.You don’t need to know how warehouses work, and Amazon doesn’t care what phone you use.Keeps jobs separate. If you change your phone app, the warehouses don’t need to change.

2.Stateless.
Every request stands alone. The server dosent "remember" what you did what you did before. e.g When you go to an ATM you put your card and enter the pin. The next time you go to the atm it dosent remember the last time you were there, each transaction is independent. simple, Scalable and Reliable.

3.Cachable.
Responses are stored (cached) to save time and reused to save time. For example if you zoom to Nairobi on Google Maps the map tiles are downloaded. If you zoom in again tomorrow the phone use the stored version instead of asking google again only traffic changes. This saves bandwith and makes app faster.

4.Uniform Interface.
All resources are accessed in the same way, with consistent rules.Example: TV Remote The power button turns any TV on/off, no matter the brand.Volume buttons always increase/decrease sound.Same interface → different TVs. Predictable, easy to use, and reduces complexity.

5.Layered System.
The client doesn’t know (or care) how many steps are in between.Sending a Letter you drop a letter at the post office.Maybe it goes through your town office → regional center → national hub → international hub → local office → delivery person. You don’t care how many layers are involved — the letter just arrives.
Adds flexibility, scalability, and security (e.g., firewalls, load balancers).

6.Code on Demand (optional)
Servers can send executable code to clients to run. Browser Plugins- You visit a website that sends you JavaScript code.Your browser runs that code to make the page interactive (like showing a live stock ticker).The website didn’t just send data — it sent logic too. Adds flexibility, but it’s optional (not all REST APIs use it).

  1. Client–Server → Shopper vs. Amazon warehouse.
  2. Stateless → ATM doesn’t remember you; each request is fresh.
  3. Cacheable → Google Maps saves tiles to load faster next time.
  4. Uniform Interface → TV remotes work the same way on all TVs.
  5. Layered System → Postal system delivers letters through many steps you don’t see.
  6. Code on Demand → Website gives you extra code (like magic tricks) to run on your device.

**

REST QUICK TIPS

1. Think in Nouns, Not Verbs
REST loves resources (things), not actions.
Example:
❌ /getAllUsers
✅ /users
👉 Imagine you have a box of toys. You don’t say:
“GoFetchAllToys”
You just say: “/toys” and people know you want toys.

2. Use the Right HTTP Methods (like tools in a toolbox)
Each method has a clear job, like buttons on a remote:
GET → Show me (read info)
POST → Add something new
PUT → Replace something completely
PATCH → Fix/update only part of something
DELETE → Throw it away

Example with /users:
GET /users → see all users
POST /users → add a new user
GET /users/1 → see user with ID 1
PUT /users/1 → replace user 1
PATCH /users/1 → update user 1’s name only
DELETE /users/1 → remove user 1

3. Use Plural Nouns for Collections
Resources are usually plural.
✅ /books, /cars, /users
❌ /getBook, /addCar, /createUser
👉 It’s like labeling boxes in a toy store: “Legos,” not “GetLego.”

4. Use Clean URLs
No ugly stuff like .php or weird verbs.
Good: /orders/123/items
Bad: /api/v1/doGetOrders.php?id=123
👉 Pretend your API is a neat bookshelf — keep the labels tidy.

5. Statelessness = No Memory Games
REST server doesn’t remember your last request.
Every request must bring its own ID card (credentials, tokens, etc.).
Example: If you order pizza 🍕, you must always tell them your address. They won’t remember it from last time.

6. Use JSON for Responses
REST usually talks in JSON because it’s lightweight and easy to read.
Example:
{
"id": 1,
"name": "Alice",
"email": "alice@example.com"
}
👉 Think of JSON like LEGO instructions: simple, structured, universal.

7. Use Status Codes to Talk Back
REST APIs talk with HTTP status codes:
200 OK → All good
201 Created → New thing added
204 No Content → Deleted successfully
400 Bad Request → You asked wrong
401 Unauthorized → You forgot your ID card
404 Not Found → Doesn’t exist
500 Server Error → Something broke on our side
👉 It’s like traffic lights 🚦 telling cars what to do.

8. Version Your API
Don’t break old toys when you add new ones.
Add versioning to URLs:
/api/v1/users
/api/v2/users
👉 Think of it like iPhone models: iPhone 14 vs iPhone 15.

9. Filtering, Sorting, and Pagination
REST APIs should let clients ask for exactly what they want.
Examples:
/users?age=18 → filter
/users?sort=age → sort
/users?page=2&limit=10 → pagination
👉 Like saying: “Show me the 10 youngest kids on page 2 of the yearbook.”

10. HATEOAS (Optional but Cool)
Fancy word meaning: API should give links to next steps.
Example:
{
"id": 1,
"name": "Alice",
"links": {
"friends": "/users/1/friends",
"posts": "/users/1/posts"
}
}
👉 It’s like a “choose your adventure” book — every page tells you where you can go next.

✅ Summary Quick List

  1. Use nouns, not verbs
  2. Use correct HTTP methods
  3. Keep URLs clean & plural
  4. Be stateless
  5. Speak in JSON
  6. Return proper status codes
  7. Version your API
  8. Add filter/sort/pagination
  9. (Optional) add links (HATEOAS)

Idempotence

🍕 Imagine this: You order a pizza online.
You click "Place Order" once. ✅ Pizza ordered.
You panic, think it didn’t go through, and click "Place Order" again.
If the system is idempotent, you still only end up with ONE pizza, not two. 🍕
That’s idempotence → doing something once or multiple times has the same result.

🖥️ In API world: GET → Always idempotent.
Asking for /users/1 again and again doesn’t change anything. You just get the same user details.

PUT → Should be idempotent.
Example: PUT /users/1 { "name": "Alice" }
If you send it once or 100 times, user 1 is still "Alice".

DELETE → Idempotent.
Deleting /users/1 once deletes it.
Trying again doesn’t bring it back or cause more damage — the user just stays deleted.

POST → Usually NOT idempotent.
Each call creates something new.
Example: POST /orders { "item": "pizza" }
Calling it 3 times = 3 different pizzas ordered. 🍕🍕🍕

Takeaway: Idempotence = no matter how many times you repeat it, the result stays the same.

**

7 Pillars of Advanced API Design.

**
1. Consistency
Same thing = same name everywhere.
Example: Don’t use /users in one place and /clients in another for the same thing.

2. Simplicity
Keep it simple, not fancy.

Example:
❌ /fetchAllActiveUserProfiles
✅ /users?status=active
**

  1. Reliability** Your API should behave the same way every time. Example: If /users/1 gives you Alice today, it should not randomly give you Bob tomorrow unless something really changed.

4. Scalability
API should handle growth.
Example:
Today you have 10 users.
Tomorrow 1 million users.
Your API should still work (with pagination: /users?page=2&limit=50).

5. Flexibility
Allow changes without breaking things.
Example: Support versioning:
/v1/users → old version
/v2/users → new version with extra fields

6. Security
Protect your data like you protect your house.
Example:
Use locks → (authentication: API keys, OAuth).
Check who can enter which room → (authorization: roles/permissions).
Don’t shout secrets → (use HTTPS, no passwords in plain text).

7. Documentation
Teach people how to use your API.
Example:
A LEGO set is useless without the manual.
Same with APIs → use docs, examples, and maybe an interactive playground (like Swagger or Postman).

🍕 Real-world analogy: Pizza Shop API

  1. Consistency → Always call it “pizza” not “pie” sometimes.
  2. Simplicity → Order with POST /orders { "item": "pizza" }, not a crazy long request.
  3. Reliability → When you order pizza, you always get pizza (not ice cream randomly).
  4. Scalability → Shop can handle 10 or 1000 pizza orders.
  5. Flexibility → They release a new menu but still support the old one.
  6. Security → Only you can order with your account, no strangers.
  7. Documentation → Menu tells you exactly what you can order and how.

Top comments (0)