Introduction to REST

REST Principles:
1. Client-Server: Separate concerns (client UI, server data/business logic)
2. Stateless: Server doesn't store client state; each request is independent
3. Cacheable: Responses can be cached (GET requests)
4. Uniform Interface: Consistent API design
5. Layered System: Clients can't tell if connected directly to end server
6. Code on Demand (optional): Server can extend client functionality (JavaScript)

HTTP Methods and Semantics:

GET /api/users             → Retrieve all users (safe, idempotent)
GET /api/users/123         → Retrieve user with ID 123
POST /api/users            → Create new user (creates new resource)
PUT /api/users/123         → Update entire user 123
PATCH /api/users/123       → Partially update user 123
DELETE /api/users/123      → Delete user 123

Safe: Doesn't modify server state (GET, HEAD, OPTIONS)
Idempotent: Multiple calls have same effect as one call (GET, PUT, DELETE)

// RESTful API example in Spring Boot
@RestController
@RequestMapping("/api/users")
public class UserController {
    private Map<Integer, User> users = new HashMap<>();
    
    // GET /api/users - Retrieve all users
    @GetMapping
    public List<User> getAllUsers() {
        return new ArrayList<>(users.values());
    }
    
    // GET /api/users/123 - Retrieve user by ID
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable int id) {
        User user = users.get(id);
        return user != null ? ResponseEntity.ok(user) : ResponseEntity.notFound().build();
    }
    
    // POST /api/users - Create new user
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        int id = users.size() + 1;
        user.setId(id);
        users.put(id, user);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }
    
    // PUT /api/users/123 - Update entire user
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable int id, @RequestBody User updatedUser) {
        if (!users.containsKey(id)) {
            return ResponseEntity.notFound().build();
        }
        updatedUser.setId(id);
        users.put(id, updatedUser);
        return ResponseEntity.ok(updatedUser);
    }
    
    // DELETE /api/users/123 - Delete user
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable int id) {
        if (!users.containsKey(id)) {
            return ResponseEntity.notFound().build();
        }
        users.remove(id);
        return ResponseEntity.noContent().build();  // 204 No Content
    }
}

Bad (not RESTful - uses verbs):
GET /api/getUsers
POST /api/createUser
PUT /api/updateUser/123
DELETE /api/deleteUser/123

Good (RESTful - uses nouns and HTTP methods):
GET /api/users
POST /api/users
PUT /api/users/123
DELETE /api/users/123

Nested resources:
GET /api/users/123/orders              → Get all orders for user 123
GET /api/users/123/orders/456          → Get specific order
POST /api/users/123/orders             → Create order for user 123

Query parameters for filtering/pagination:
GET /api/users?age=25                  → Filter by age
GET /api/users?page=2&limit=10         → Pagination
GET /api/users?sort=name&order=asc     → Sorting
GET /api/products?category=electronics&price_max=1000  → Multiple filters

class User {
    @JsonProperty("user_id")  // Customize JSON field name
    private int id;
    
    @JsonIgnore               // Exclude from JSON
    private String password;
    
    @JsonFormat(pattern = "yyyy-MM-dd")  // Date formatting
    private java.util.Date createdAt;
    
    // ... getters/setters
}

// Spring Boot automatically converts User to JSON:
// {"user_id": 123, "name": "Alice", "email": "alice@example.com", "createdAt": "2023-01-15"}

@RestController
@RequestMapping("/api/users")
public class UserController {
    // Explicitly specify content type
    @GetMapping(produces = "application/json")
    public User getUser() {
        return new User(1, "Alice");
    }
    
    // Support multiple content types
    @GetMapping(produces = {"application/json", "application/xml"})
    public User getUserMultiFormat() {
        return new User(1, "Alice");
    }
    
    // Client sends JSON, server responds with JSON
    @PostMapping(consumes = "application/json", produces = "application/json")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // ... create user
        return ResponseEntity.status(201).body(user);
    }
}

@RestController
@RequestMapping("/api/products")
public class ProductController {
    private List<Product> products = loadProducts();
    
    // Pagination: GET /api/products?page=2&size=10
    @GetMapping
    public ResponseEntity<Page<Product>> getProducts(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") int size) {
        
        int startIndex = (page - 1) * size;
        int endIndex = Math.min(startIndex + size, products.size());
        
        List<Product> pageContent = products.subList(startIndex, endIndex);
        Page<Product> result = new Page<>(pageContent, page, size, products.size());
        
        return ResponseEntity.ok(result);
    }
    
    // Filtering and sorting: GET /api/products?category=electronics&minPrice=100&sort=price&order=asc
    @GetMapping("/search")
    public List<Product> searchProducts(
            @RequestParam(required = false) String category,
            @RequestParam(required = false) Double minPrice,
            @RequestParam(defaultValue = "name") String sort,
            @RequestParam(defaultValue = "asc") String order) {
        
        List<Product> filtered = products.stream()
            .filter(p -> category == null || p.getCategory().equals(category))
            .filter(p -> minPrice == null || p.getPrice() >= minPrice)
            .collect(java.util.stream.Collectors.toList());
        
        // Sort
        if ("price".equals(sort)) {
            filtered.sort((a, b) -> Double.compare(a.getPrice(), b.getPrice()));
        } else {
            filtered.sort((a, b) -> a.getName().compareTo(b.getName()));
        }
        
        if ("desc".equals(order)) {
            java.util.Collections.reverse(filtered);
        }
        
        return filtered;
    }
}

class Page<T> {
    private List<T> content;
    private int currentPage;
    private int pageSize;
    private int totalItems;
    private int totalPages;
    
    Page(List<T> content, int currentPage, int pageSize, int totalItems) {
        this.content = content;
        this.currentPage = currentPage;
        this.pageSize = pageSize;
        this.totalItems = totalItems;
        this.totalPages = (totalItems + pageSize - 1) / pageSize;
    }
    
    // Getters...
    public List<T> getContent() { return content; }
    public int getCurrentPage() { return currentPage; }
    public int getTotalPages() { return totalPages; }
}