How APIs Work (REST API Guide)

 

Introduction

Have you ever wondered how apps like Instagram, Swiggy, YouTube, or Amazon fetch data, show feeds, and process payments instantly? Behind the scenes, software systems talk to each other using APIs — the invisible bridges that transfer data, trigger actions, and connect services.

This guide focuses on REST APIs — the most common type of web APIs used by developers worldwide. Whether you’re a student, a beginner developer, or a product-minded person who wants to understand how modern web systems communicate, this article will give you a practical, step-by-step understanding of REST API basics, examples, and best practices.

What you’ll learn: - What an API is, in plain English
- How REST (Representational State Transfer) works
- Key HTTP methods and status codes
- Endpoints, parameters, headers, and request bodies
- Authentication patterns (API keys, JWT, OAuth)
- How to design, build, and test a simple REST API
- Real-world examples and common pitfalls
- Actionable tips to become productive quickly

Let’s get started.

---

What Is an API?

API stands for Application Programming Interface. It’s a set of rules and tools that allows two software programs to talk to each other.

Analogy: Think of an API as a waiter in a restaurant: you (the client) place an order, the waiter (API) delivers it to the kitchen (server), and brings the response (food) back to you.

APIs hide internal implementation details and expose specific capabilities, making systems modular and easier to integrate.

---

REST — The Style of Modern Web APIs

REST stands for Representational State Transfer, coined by Roy Fielding. It’s not a protocol, but an architectural style with constraints that make web services scalable and simple.

Core REST principles: - Client–server separation: Clients and servers can evolve independently.
- Statelessness: Each request carries all the information needed — the server does not store client state between requests.
- Cacheability: Responses should indicate whether they can be cached to improve performance.
- Uniform interface: Resources are identified using URLs and manipulated via a limited set of HTTP methods.
- Layered system: Architecture can include intermediaries like proxies, gateways, and load balancers.

Why REST? It’s simple, uses standard web protocols (HTTP/HTTPS), and maps naturally to CRUD operations.

---

Key HTTP Methods (CRUD Mapping)

REST APIs use HTTP methods to represent actions:

• GET — Retrieve resource(s). (Read)
  
• POST — Create a new resource. (Create)
  
• PUT — Replace an existing resource (full update). (Update)
  
• PATCH — Modify a resource partially. (Partial update)
  
• DELETE — Remove a resource. (Delete)

Example: Products resource

GET /products         // list products
GET /products/123     // get product 123
POST /products        // create product
PUT /products/123     // replace product 123
PATCH /products/123   // update parts of product 123
DELETE /products/123  // delete product 123

---

URL Design and Endpoints

Good endpoint design is consistent, resource-oriented, and intuitive.

Guidelines: - Use nouns, not verbs. /orders, not /getOrders.
- Keep endpoints plural (/users, /products).
- Use hierarchical URLs for relationships (/users/42/orders).
- Version your API /v1/users to allow safe evolution.

Example endpoints and meanings: - /users — collection of users
- /users/42 — single user with ID 42
- /users/42/orders — orders for that user

---

Path vs Query Parameters vs Request Body

• Path parameters identify a specific resource: /users/{id}.
  
• Query parameters refine/filter the result: /products?category=clothes&sort=price.
  
• Request body contains data sent by the client for POST/PUT/PATCH operations (usually JSON).

Always validate and sanitize inputs to avoid errors and security issues.

---

Headers — Metadata of Requests

HTTP headers carry metadata and instructions:

• Content-Type: indicates media type (e.g., application/json).
  
• Accept: desired response format.
  
• Authorization: credentials (Bearer tokens / API keys).
  
• Cache-Control: caching policies.

Example:

Authorization: Bearer eyJhbGci...
Content-Type: application/json

---

JSON — The Common Data Format

REST commonly uses JSON (JavaScript Object Notation) to transmit structured data.

Example response:

{
  "status": "success",
  "data": {
    "id": 101,
    "name": "Wireless Mouse",
    "price": 29.99,
    "stock": 120
  }
}

Design responses to be consistent and predictable (wrap with data, error, meta where helpful).

---

HTTP Status Codes — Communicating Outcomes

Use proper HTTP status codes — they are the canonical contract between client and server.

• 200 OK — Success
  
• 201 Created — Resource created (use with POST)
  
• 204 No Content — Success with no response body (e.g., successful DELETE)
  
• 400 Bad Request — Client-side input issue
  
• 401 Unauthorized — Invalid or missing authentication
  
• 403 Forbidden — Authentication OK but not allowed
  
• 404 Not Found — Resource doesn’t exist
  
• 409 Conflict — Duplicate resource or version conflict
  
• 422 Unprocessable Entity — Semantic validation error (e.g., missing fields)
  
• 500 Internal Server Error — Server-side error

Return error objects with message, code, and details to help debugging.

---

Authentication & Authorization

Common patterns:

API Keys - Simple token sent in headers. - Good for server-to-server requests but limited granularity.

JWT (JSON Web Tokens) - Tokens issued at login; include user info and expiry. - Stateless and widely used for SPA/mobile authentication.

OAuth 2.0 - Delegated access for third-party apps (used by Google, Facebook). - More complex but secure for delegated permissions.

Best practices - Always use HTTPS.
- Rotate keys and use short-lived tokens.
- Store secrets securely (env variables / secret manager).

---

Rate Limiting, Pagination & Caching

To scale and protect your API:

Rate limiting: Prevent abuse by limiting requests per IP or API key (e.g., 100 req/min).
Pagination: For large collections use limit & offset or cursor-based pagination.
Caching: Use Cache-Control headers and CDN caching for public data.

Example pagination query:

GET /products?limit=20&offset=40

---

Designing Responses & Versioning

• Keep responses small and consistent.
  
• Use HATEOAS sparingly — most APIs rely on simple links.
  
• Version your API using URLs (/v1/) or headers (Accept: application/vnd.myapi.v1+json).
  
• Deprecate old endpoints gracefully with clear migration guides.

---

Building a Simple REST API — Example (Node.js + Express)

Here’s a minimal, complete example to illustrate core concepts:

// server.js
const express = require('express');
const app = express();
app.use(express.json());

let products = [
  { id: 1, name: 'Laptop', price: 999 },
  { id: 2, name: 'Mouse', price: 19 }
];

// List products (GET)
app.get('/v1/products', (req, res) => {
  res.json({ status: 'success', data: products });
});

// Get single product (GET)
app.get('/v1/products/:id', (req, res) => {
  const product = products.find(p => p.id === +req.params.id);
  if (!product) return res.status(404).json({ status: 'error', message: 'Product not found' });
  res.json({ status: 'success', data: product });
});

// Create product (POST)
app.post('/v1/products', (req, res) => {
  const { name, price } = req.body;
  if (!name || price == null) return res.status(422).json({ status: 'error', message: 'Invalid input' });
  const id = products.length + 1;
  const newProduct = { id, name, price };
  products.push(newProduct);
  res.status(201).json({ status: 'success', data: newProduct });
});

// Delete product (DELETE)
app.delete('/v1/products/:id', (req, res) => {
  products = products.filter(p => p.id !== +req.params.id);
  res.status(204).send();
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

Run and test with curl or Postman.

---

Testing APIs

Tools: - Postman — GUI for requests and collections.
- curl — command-line testing.
- Automated tests — Mocha, Jest, SuperTest for Node.js APIs.

Write tests for happy paths, edge cases, and error handling.

---

Security Considerations

• Use HTTPS/TLS.
  
• Validate and sanitize all inputs (avoid injection).
  
• Implement authentication and authorization correctly.
  
• Limit payload sizes.
  
• Monitor and log suspicious behavior.
  
• Implement CORS properly for browser-based clients.

---

REST vs GraphQL vs gRPC (Short Comparison)

• REST: Simple, resource-based, flexible. Great for standard CRUD APIs.
  
• GraphQL: Client can request exactly the fields they need. Useful for complex clients and variable queries.
  
• gRPC: High-performance RPC using Protocol Buffers, ideal for internal microservices.

Choose based on use case: public APIs often use REST; internal high-performance services may use gRPC; client-driven APIs can benefit from GraphQL.

---

Common Mistakes & How to Avoid Them

• Using verbs in URIs (/getUser) — use nouns.
  
• Returning inconsistent response formats.
  
• Ignoring proper status codes.
  
• Not handling partial updates or concurrency.
  
• Skipping input validation.
  
• Not documenting the API.

Use API specs (OpenAPI/Swagger) to document and generate clients.

---

Short Summary

REST APIs allow systems to communicate over HTTP using standardized methods, resource URLs, and structured data (JSON). They are stateless, cache-friendly, and simple to implement and scale.

Learning REST basics — endpoints, methods, headers, status codes, authentication — unlocks the ability to build and integrate modern applications.

---

Conclusion

APIs are the glue of modern software. REST remains a practical and widely adopted approach for building web services. With a solid understanding of REST principles, request/response patterns, security, and testing, you can design APIs that are reliable, performant, and developer-friendly.

Start small, iterate, add monitoring and documentation, and your services will serve users and other developers well.

---

FAQs

1. What is a REST API in simple terms?

A REST API is a web-based interface that lets two systems exchange data using HTTP and standard methods like GET and POST.

2. When should I use REST vs GraphQL?

Use REST for simple, resource-oriented APIs. Use GraphQL when clients need flexible querying of nested data.

3. What is statelessness?

Each request must contain all information required for the server to understand and process it—no session stored on the server.

4. How do I version my API?

Commonly with path versioning: /v1/.... You can also use headers for versioning.

5. How do I secure my API?

Use HTTPS, authenticate requests, validate input, and implement rate limiting and logging.

---

References

https://en.wikipedia.org/wiki/API
https://en.wikipedia.org/wiki/Web_API
https://en.wikipedia.org/wiki/Representational_state_transfer
https://en.wikipedia.org/wiki/JSON
https://swagger.io/docs/

---

Feature Image Link

https://images.unsplash.com/photo-1558494949-ef010cbdcc31