Skip to main content

REST API Methods & API Design – Detailed Notes

HTTP Methods Overview​

  • There are 5 major HTTP methods used for data operations:

    • GET
    • POST
    • PUT
    • PATCH
    • DELETE

  • Other methods:

    • HEAD → fetch headers only
    • OPTIONS → used in CORS to check allowed origins

Idempotency (Very Important Concept)​

Definition​

  • A method is idempotent if:

    • Performing it multiple times results in the same state on the server
    • Focus is on side effects on server, not response differences

GET Method​

  • Used to retrieve data
  • Example: Fetch list of books

Properties​

  • Idempotent

    • Multiple calls → no change in server state

  • Even if response changes (due to new data), still idempotent because:

    • No side effect caused by client

PUT vs PATCH​

PATCH​

  • Used to partially update a resource

  • Example:

    • Only update name field of user

PUT​

  • Used to completely replace a resource

  • Must send full object

    • ID, name, createdAt, etc.

Key Difference​

  • PATCH → partial update
  • PUT → full replacement

Important Note​

  • In practice:

    • Often used interchangeably

  • But in public APIs:

    • Follow standards strictly to avoid confusion

Idempotency of PUT & PATCH​

  • Example:

    • Update name from A → B

    • Repeating same request:

      • B → B (no further change)

Conclusion​

  • Both are idempotent
  • Same request → same final state

DELETE Method​

  • Used to delete a resource

Behavior​

  • First call:

    • Resource deleted

  • Second call:

    • Returns error (404 – not found)

Idempotency​

  • Still idempotent

    • No additional side effects after first call

POST Method​

  • Used to create new resource

Behavior​

  • Each request:

    • Creates a new entity

  • Example:

    • Same payload → multiple books created (different IDs)

Idempotency​

  • NOT idempotent

    • Each request causes different side effects

POST for Custom Actions​

  • POST is open-ended
  • Used when action doesn’t fit CRUD

Example​

  • POST /send-email

    • Not:

      • GET
      • PUT
      • DELETE

    • It’s a custom action

Conclusion​

  • Use POST for:

    • Create
    • Custom operations

API Design Principles

Why Follow Standards?​

  • Without standards:

    • Developers must:

      • Read code OR
      • Trial-and-error API behavior

Problems​

  • Confusion
  • Bugs
  • Integration difficulty

Benefits of Standards​

  • No guesswork
  • Predictable behavior
  • Faster integration
  • Better developer experience

API Design Workflow​

Step 1: Start from UI (Figma / Wireframes)​

  • Understand:

    • How users interact with data

  • Helps connect:

    • UI → Backend → Database

Resources (Core REST Concept)​

Definition​

  • Resources = Nouns in system

Example (Project Management App)​

  • Projects
  • Users
  • Organizations
  • Tasks
  • Tags

Workflow Summary​

  1. Analyze UI / requirements
  2. Identify resources (nouns)
  3. Design DB schema
  4. Define API endpoints
  5. Implement logic

CRUD Actions​

For each resource:

  • Create
  • Read (single + list)
  • Update
  • Delete

API Endpoint Design

Naming Conventions​

  • Use plural nouns

    • /organizations

  • Use lowercase

  • Example:

    • GET /organizations
    • POST /organizations

GET vs POST Same URL​

  • Differentiated by HTTP method:

    • GET → fetch
    • POST → create

POST Response​

  • Status code: 201 Created

  • Returns:

    • Newly created entity

GET Response​

  • Status code: 200 OK

  • Returns:

    • Data list

Pagination

Why Pagination?​

  • Avoid:

    • Large payloads
    • High latency
    • Poor UX

Benefits​

  • Faster responses
  • Less load
  • Better UI experience

Pagination Parameters​

  • limit → items per page
  • page → page number

Default Behavior​

  • Server should set defaults:

    • page = 1
    • limit = 10 or 20

Pagination Response Format​

  • data → current page items
  • total → total items in DB
  • page → current page
  • totalPages → total pages

Example​

  • Total = 5, limit = 2:

    • Page 1 → 2 items
    • Page 2 → 2 items
    • Page 3 → 1 item

Sorting

Why Sorting?​

  • Without sorting:

    • DB returns random order

Sorting Parameters​

  • sortBy → field (name, id, etc.)
  • sortOrder → asc / desc

Default Sorting​

  • Field: createdAt

  • Order: desc

  • Reason:

    • Show latest entries first

Key Principle​

  • Server should:

    • Handle defaults
    • Not depend on client for obvious parameters

Key Takeaways

  • Idempotency is about server-side effects

  • GET, PUT, PATCH, DELETE → idempotent

  • POST → non-idempotent

  • Always:

    • Follow REST standards
    • Design from UI → backend
    • Use pagination + sorting
    • Provide sensible defaults