What is the difference between REST and RESTful API?

// REST - architecture principles
// RESTful API - practical implementation
GET /api/users/123     // ✅ RESTful implementation of REST principles
POST /getUserById      // ❌ Not RESTful, doesn't follow REST

// REST - set of principles:
// 1. Client-Server architecture
// 2. Stateless
// 3. Cacheable
// 4. Uniform Interface
// 5. Layered System
// 6. Code on Demand

// RESTful API - practical implementation
const api = {
  getUsers: () => fetch('/api/users'),           // GET
  createUser: (data) => fetch('/api/users', {    // POST
    method: 'POST',
    body: JSON.stringify(data)
  }),
  updateUser: (id, data) => fetch(`/api/users/${id}`, { // PUT
    method: 'PUT',
    body: JSON.stringify(data)
  }),
  deleteUser: (id) => fetch(`/api/users/${id}`, { // DELETE
    method: 'DELETE'
  })
};

// REST - conceptual level
// Defines WHAT should be
 
// RESTful - practical level
// Defines HOW to implement it

// Must comply with ALL 6 principles
// Complete stateless architecture
// Mandatory cacheability
// Strict uniform interface

// Can partially follow principles
// Practical compromises
// Adaptation to real tasks

// Correct HTTP methods usage
GET    /api/products        // Get all products
GET    /api/products/123    // Get product by ID
POST   /api/products        // Create new product
PUT    /api/products/123    // Update product completely
PATCH  /api/products/123    // Partially update product
DELETE /api/products/123    // Delete product

// Incorrect usage
POST /api/getProducts       // ❌ GET in POST
GET  /api/deleteUser/123    // ❌ DELETE in GET
POST /api/updateUserName    // ❌ UPDATE in POST

// RESTful stateless implementation
// Each request contains all necessary information
const headers = {
  'Authorization': 'Bearer token123',
  'Content-Type': 'application/json'
};
 
fetch('/api/user/profile', { headers }); // ✅ All info in request

// RESTful uniformity
const apiEndpoints = {
  users: '/api/users',
  products: '/api/products', 
  orders: '/api/orders'
};
 
// Same operations for all resources
// GET, POST, PUT, DELETE work the same way

// RESTful resources
/api/users          // Collection of users
/api/users/123      // Specific user
/api/users/123/posts // User's posts
 
// Not RESTful
/api/getUserById/123     // ❌ Action in URL
/api/createNewUser       // ❌ Action in URL

// REST theory - ideal world
// All 6 principles mandatory
// Complete stateless architecture
// Strict standard compliance
 
// RESTful practice - real world
// Compromises for performance
// Adaptation to business requirements
// Practicality over purity

// RESTful compromises
// Client-side caching (violates stateless)
localStorage.setItem('userToken', token);
 
// Batch operations (deviation from uniform interface)
POST /api/users/batch-update
 
// Search with parameters (URL flexibility)
GET /api/products?search=laptop&category=electronics

// Level 0 - Plain Old XML (POX)
POST /api/endpoint
// One URL, one HTTP method
 
// Level 1 - Resources
GET /api/users
GET /api/products
// Multiple URLs, one HTTP method
 
// Level 2 - HTTP methods
GET    /api/users     // ✅ RESTful starts here
POST   /api/users
PUT    /api/users/123
DELETE /api/users/123
 
// Level 3 - HATEOAS
{
  "id": 123,
  "name": "John",
  "_links": {
    "self": "/api/users/123",
    "posts": "/api/users/123/posts"
  }
}

// ✅ RESTful URL structure
/api/v1/users                    // Collection
/api/v1/users/123               // Item
/api/v1/users/123/posts         // Nested collection
/api/v1/users/123/posts/456     // Nested item
 
// ❌ Not RESTful
/api/getUser?id=123
/api/createUser
/api/user_delete/123

// RESTful status codes usage
const responses = {
  200: 'OK - successful GET, PUT',
  201: 'Created - successful POST',
  204: 'No Content - successful DELETE',
  400: 'Bad Request - client error',
  401: 'Unauthorized - no authorization',
  404: 'Not Found - resource not found',
  500: 'Internal Server Error - server error'
};

// Tools for checking RESTful API
// - Postman Collections
// - Swagger/OpenAPI
// - REST API validators
 
// Evaluation criteria:
// ✅ Uses HTTP methods correctly
// ✅ Resources in URLs, not actions
// ✅ Correct status codes
// ✅ Consistent response structure

// GraphQL - RESTful alternative
query {
  user(id: 123) {
    name
    posts {
      title
    }
  }
}
 
// gRPC - for high-performance APIs
// WebSocket - for real-time communication

GET /api/deleteUser/123    // Action in URL + wrong method
POST /api/users/getAll     // GET operation via POST

DELETE /api/users/123      // Correct method and resource
GET /api/users             // Correct method for retrieval