---

Introduction

Almost every modern application communicates using REST APIs.

Examples:

• Amazon Product APIs
• Netflix Catalog APIs
• Uber Ride APIs
• Banking Payment APIs
• Google Maps APIs
• Stripe Payment APIs

Whenever a mobile app displays data, it usually calls a REST API.

For example:

Customer Opens Banking App

↓

GET /accounts

↓

Account Balance Returned

A poorly designed API leads to:

• Slow applications
• Difficult integrations
• Security issues
• High maintenance costs
• Breaking changes

A well-designed REST API is:

• Simple
• Predictable
• Scalable
• Secure
• Easy to consume

---

Learning Objectives

After completing this article, you will understand:

• What is REST?
• REST Principles
• Resource Modeling
• URI Design
• HTTP Methods
• Request & Response Design
• Status Codes
• Pagination
• Filtering
• Sorting
• Versioning
• Idempotency
• Security
• Best Practices

---

What is REST?

REST stands for

Representational State Transfer

REST is an architectural style where everything is treated as a Resource.

Examples

Resource	URI
Customer	/customers
Account	/accounts
Orders	/orders
Products	/products
Payments	/payments

---

REST Architecture

flowchart LR
    A[Mobile App]
    B[REST API]
    C[Spring Boot]
    D[(Database)]

    A --> B
    B --> C
    C --> D

---

REST Request Flow

flowchart LR
    A[Client]

    B[API Gateway]

    C[Authentication]

    D[REST Controller]

    E[Service]

    F[Repository]

    G[(Database)]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G

---

REST Principles

REST APIs should follow these principles:

• Client-Server Architecture
• Stateless Communication
• Resource-Based URIs
• Uniform Interface
• Cacheable Responses
• Layered Architecture

---

Resource-Based Design

Bad

/getCustomerData

Good

/customers

Bad

/createOrder

Good

/orders

Always use resources, not actions.

---

URI Design

Good Examples

/customers

/customers/1001

/orders

/orders/500

/accounts

/accounts/12345

Bad Examples

/getCustomers

/deleteCustomer

/createOrder

/updateAccount

---

HTTP Methods

Method	Purpose
GET	Retrieve data
POST	Create resource
PUT	Replace resource
PATCH	Partial Update
DELETE	Delete resource

---

Customer API

Get all customers

GET /customers

Get one customer

GET /customers/1001

Create customer

POST /customers

Update customer

PUT /customers/1001

Delete customer

DELETE /customers/1001

---

Banking Example

Money Transfer

POST /payments

Request

{
  "fromAccount":"10001",
  "toAccount":"20001",
  "amount":500
}

Response

{
  "transactionId":"TXN123456",
  "status":"SUCCESS"
}

---

REST API Flow

flowchart TD

    A[Customer]

    B[Mobile App]

    C[API Gateway]

    D[Payment API]

    E[Core Banking]

    F[(Database)]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

---

HTTP Status Codes

Status	Meaning
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Validation Failed
500	Internal Server Error
503	Service Unavailable

---

Request Headers

Common Headers

Authorization: Bearer JWT

Content-Type: application/json

Accept: application/json

Correlation-Id: abc123

---

Response Example

{
  "customerId":1001,
  "name":"John",
  "city":"Dallas"
}

---

Error Response Design

Bad

{
   "error":"Something went wrong"
}

Good

{
   "timestamp":"2026-06-26T12:00:00Z",
   "status":404,
   "error":"Customer Not Found",
   "path":"/customers/1001"
}

---

Pagination

Never return millions of records.

Bad

GET /transactions

Good

GET /transactions?page=0&size=20

---

Pagination Flow

flowchart LR
    A[Client]

    B[API]

    C[(Database)]

    D[20 Records]

    A --> B
    B --> C
    C --> D

---

Filtering

Example

GET /orders?status=SHIPPED

---

Sorting

GET /customers?sort=name

Descending

GET /customers?sort=name,desc

---

Searching

GET /products?q=laptop

---

API Versioning

Versioning prevents breaking existing clients.

URI Versioning

/api/v1/customers

/api/v2/customers

---

Versioning Architecture

flowchart TD

    A[Clients]

    B[API Gateway]

    C[v1 APIs]

    D[v2 APIs]

    A --> B
    B --> C
    B --> D

---

Idempotency

Critical for payment APIs.

Customer clicks

Pay Now

three times.

Without Idempotency

Payment 1

Payment 2

Payment 3

With Idempotency

Payment

↓

Idempotency Key

↓

Single Transaction

---

API Security

Secure APIs using

• HTTPS
• OAuth2
• JWT
• API Keys
• Rate Limiting

---

Secure API Flow

flowchart LR

    A[Client]

    B[OAuth2]

    C[JWT]

    D[API Gateway]

    E[Spring Boot]

    A --> B
    B --> C
    C --> D
    D --> E

---

Rate Limiting

Protect APIs from abuse.

Example

100 Requests

↓

Per Minute

↓

Per User

---

API Gateway

flowchart TD

    A[Clients]

    B[API Gateway]

    C[Customer Service]

    D[Order Service]

    E[Payment Service]

    A --> B

    B --> C
    B --> D
    B --> E

Responsibilities

• Authentication
• Authorization
• Routing
• Rate Limiting
• Logging

---

Banking Example

Transfer Money

POST /payments

Check Transaction

GET /payments/TXN10001

Cancel Transfer

DELETE /payments/TXN10001

---

Amazon Example

GET /products

GET /products/100

POST /orders

GET /orders/500

---

Uber Example

POST /rides

GET /rides/500

PATCH /rides/500

---

Netflix Example

GET /movies

GET /movies/100

GET /recommendations

---

REST API Best Practices

• Use nouns instead of verbs.
• Keep URIs simple.
• Return meaningful status codes.
• Validate every request.
• Always use HTTPS.
• Design idempotent APIs.
• Support pagination.
• Implement filtering and sorting.
• Version public APIs.
• Return consistent error responses.

---

Common Mistakes

❌ Using verbs in URLs

❌ Returning HTTP 200 for errors

❌ No pagination

❌ No versioning

❌ Exposing internal database IDs unnecessarily

❌ Inconsistent JSON responses

❌ No authentication

❌ Returning stack traces

---

Monitoring REST APIs

Monitor

• Response Time
• P95 Latency
• Error Rate
• Requests/sec
• HTTP Status Codes
• Authentication Failures
• Rate Limit Violations

Tools

• Prometheus
• Grafana
• Datadog
• CloudWatch

---

Common Interview Questions

What is REST?

REST is an architectural style that models everything as resources accessed through standard HTTP methods.

---

Why should URIs use nouns instead of verbs?

Resources represent business entities, while HTTP methods already define the action (GET, POST, PUT, DELETE).

---

Why is pagination important?

Pagination prevents excessive memory usage, reduces response size, improves latency, and provides a better user experience.

---

Why are idempotent APIs important?

They prevent duplicate processing when requests are retried because of network failures or timeouts, especially for financial operations.

---

Why should APIs be versioned?

Versioning allows new functionality to be introduced without breaking existing clients.

---

Summary

REST APIs are the communication backbone of modern distributed systems. Well-designed APIs are easy to understand, scalable, secure, and maintainable.

In this article, we covered:

• REST fundamentals
• Resource modeling
• URI design
• HTTP methods
• Request and response structures
• Status codes
• Pagination
• Filtering
• Sorting
• Versioning
• Idempotency
• Security
• API Gateway
• Real-world examples
• Best practices

Designing REST APIs correctly is a foundational skill for every Backend Engineer and Solution Architect. Clean API design simplifies integration, improves developer experience, and enables enterprise systems to evolve without disrupting consumers.

---