RESTful API Architecture Principles

Designing Clean REST APIs

REST (Representational State Transfer) is an architectural style for designing networked applications using stateless communications and HTTP standard verbs.

Key Rules of RESTful API Design

1. Nouns over Verbs for Endpoints: Use plural resource nouns instead of action verbs.

• Good: GET /api/v1/users
• Bad: GET /api/v1/getUsers or POST /api/v1/deleteUser

1. Stateless Requests: Every request must contain all information required to fulfill it (e.g. JWT Auth headers).
2. Standard HTTP Verbs:

• GET: Fetch resource(s) (Safe & Idempotent).
• POST: Create a resource (Non-idempotent).
• PUT: Replace a resource entirely (Idempotent).
• PATCH: Partial update of resource (Non-idempotent).
• DELETE: Delete a resource (Idempotent).

1. Hierarchical Nested Resources:

• GET /api/v1/users/42/posts (Fetches posts belonging to user 42).

TL;DR

• Use plural nouns for resource paths (/api/v1/products).
• Rely on HTTP methods (GET, POST, PUT, DELETE) to specify operations rather than URL verbs.