A Full Guide: Understand Everything About APIs with Examples

You might have heard the term API before. But what exactly does it mean, and why is it important?

In simple terms, an API (Application Programming Interface) is a way for different computer programs to talk to each other. Think of it like a secret code that one program can use to ask another program for information or ask it to do something.

---

Mindset When Building an API

APIs save time, encourage collaboration, and unlock innovation. For example, a developer might use a weather API and combine it with traffic data to create a smarter navigation app.

---

What are the Different Types of APIs?

• SOAP APIs: XML-based, structured, strict.
• XML-RPC APIs: RPC style with XML payloads.
• REST APIs: Lightweight, stateless, use HTTP methods.
• JSON-RPC APIs: RPC with JSON payloads.
• GraphQL APIs: Query-based, efficient, modern.
• OpenAPI/Swagger: Machine-readable API contracts.

APIs are also categorized as Public, Partner, Internal, Composite, or B2B.

---

Understanding XML vs JSON

• XML: Verbose, tag-based, structured.
• JSON: Lightweight, human-friendly, widely used.

---

Decoding REST APIs

REST APIs are stateless and use HTTP verbs like GET, POST, PUT, and DELETE.

Example request:

GET https://api.weather.com/forecast?zip=90210&appid=YOUR_API_KEY

Response:

{
  "location": "90210",
  "forecast": "Sunny, 25°C"
}

---

CRUD Operations with REST

Retrieve Data (GET):

fetch("https://api.example.com/data")
  .then(res => res.json())
  .then(console.log);

Create Data (POST):

import requests
response = requests.post("https://api.example.com/data", json={"name": "John"})
print(response.json())

Update Data (PUT):

fetch("https://api.example.com/data/123", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ age: 26 })
})

Delete Data (DELETE):

import requests
requests.delete("https://api.example.com/data/123")

---

Securing a REST API

1. Use HTTPS
2. Implement Authentication/Authorization (JWT, OAuth)
3. Apply Rate Limiting
4. Validate Input

Example: JWT Authentication in Express.js

app.get("/protected", (req, res) => {
  const token = req.headers["authorization"].split(" ")[1];
  jwt.verify(token, "secret", (err, user) => {
    if (err) return res.sendStatus(403);
    res.send(`Welcome, ${user.name}`);
  });
});

---

Writing API Documentation

• Be clear and concise
• Provide examples
• Document parameters and responses

Example (Weather API):

GET /weather?location=London&units=metric

Response:

{
  "location": "London",
  "temperature": 10,
  "conditions": "Cloudy"
}

---

Full Example: Building a Flask API

from flask import Flask, jsonify, request
app = Flask(__name__)

products = [
  {"id": 1, "name": "Product 1", "price": 10.0},
  {"id": 2, "name": "Product 2", "price": 20.0},
]

@app.route("/products", methods=["GET"])
def get_products():
    return jsonify(products)

@app.route("/products/<int:id>", methods=["GET"])
def get_product(id):
    return jsonify(next((p for p in products if p["id"] == id), {"message": "Not found"}))

if __name__ == "__main__":
    app.run(debug=True)

---

Conclusion

APIs power modern applications by enabling communication between systems.
From social logins to weather apps to e-commerce APIs, they are the backbone of connectivity.
Understanding REST, data formats, and security practices ensures you can build, consume, and scale APIs effectively.