RESTful API Basics

---

What is REST?

"Representational State Transfer"

REST is an architectural style for designing web services that use standard HTTP methods.

"REST is an architectural style for web services that uses standard HTTP methods, stateless communication, and resource-based URLs."

---

REST Principles

SCURP = 5 principles

Letter	Principle
S	Stateless
C	Client-Server
U	Uniform Interface
R	Resource-based
P	Cacheable

"REST principles: Stateless, Client-Server separation, Uniform Interface, Resource-based URIs, and Cacheable responses."

---

HTTP Methods

GET · POST · PUT · DELETE · PATCH

Method	Purpose	Idempotent	Safe
GET	Retrieve	✅	✅
POST	Create	❌	❌
PUT	Update/Replace	✅	❌
DELETE	Delete	✅	❌
PATCH	Partial Update	❌	❌

"REST uses HTTP methods: GET (read), POST (create), PUT (update), DELETE (remove), PATCH (partial update)."

---

Resource-Based URLs

Nouns, not verbs

✅ Good:
GET /api/users
GET /api/users/123
POST /api/users

❌ Bad:
GET /api/getUsers
GET /api/userById?id=123
POST /api/createUser

"REST URLs use nouns (resources), not verbs. URLs represent resources, HTTP methods represent actions."

---

Stateless

Each request is independent

• No server-side session state
• Each request contains all needed info
• Server doesn't remember previous requests
• Scalable and simple

"REST is stateless - each request is independent, containing all information needed, with no server-side session state."

---

Status Codes

2xx success, 4xx client error, 5xx server error

Code	Meaning
200	OK
201	Created
204	No Content
400	Bad Request
401	Unauthorized
404	Not Found
500	Server Error

"REST uses HTTP status codes: 2xx (success), 4xx (client error), 5xx (server error)."

---

Request/Response Format

JSON typically, but flexible

GET /api/users/123
Accept: application/json

Response:
Content-Type: application/json
{
  "id": 123,
  "name": "John"
}

"REST APIs typically use JSON for request/response bodies, though format is flexible."

---

RESTful Design

Resources · Collections · Actions

Resources:
GET    /api/users          # List all
GET    /api/users/123      # Get one
POST   /api/users          # Create
PUT    /api/users/123      # Update
DELETE /api/users/123      # Delete

Nested:
GET    /api/users/123/posts  # User's posts

"RESTful design uses resource-based URLs with HTTP methods, supporting nested resources for relationships."

---

HATEOAS (Optional)

"Hypermedia as the Engine of Application State"

{
  "id": 123,
  "name": "John",
  "links": [
    { "rel": "self", "href": "/api/users/123" },
    { "rel": "posts", "href": "/api/users/123/posts" }
  ]
}

Advanced REST concept - responses include links to related resources.

"HATEOAS is an advanced REST concept where responses include links to related resources, enabling discoverable APIs."

---

Best Practices

✅ Use proper HTTP methods ✅ Use resource-based URLs ✅ Return appropriate status codes ✅ Use JSON for data ✅ Version APIs (/api/v1/) ✅ Document with OpenAPI/Swagger ✅ Handle errors consistently ❌ Don't use verbs in URLs ❌ Don't ignore status codes

---

"REST is an architectural style using HTTP methods (GET/POST/PUT/DELETE), resource-based URLs (nouns), stateless communication, and standard status codes. It follows principles: stateless, client-server, uniform interface, resource-based, and cacheable. RESTful APIs use JSON, proper HTTP methods, and return appropriate status codes."

---

🧠 Ultra-Short Cheat Sheet

HTTP methods (GET/POST/PUT/DELETE)
Resource-based URLs (nouns)
Stateless
Status codes (2xx/4xx/5xx)
JSON format
Version APIs
Document with Swagger