// Express / Fastify
import { Router, Request, Response } from 'express';

const router = Router();

router.get('/users', async (req: Request, res: Response) => {
  const { page = '1', limit = '20', sort = 'createdAt', order = 'desc', role } = req.query;

  const filters = { ...(role && { role: String(role) }) };
  const pagination = { page: Number(page), limit: Math.min(Number(limit), 100) };
  const sorting = { field: String(sort), direction: String(order) as 'asc' | 'desc' };

  const result = await userService.listUsers(filters, pagination, sorting);

  res
    .set('Cache-Control', 'private, max-age=60')
    .set('X-Total-Count', String(result.total))
    .status(200)
    .json({
      data: result.users,
      pagination: {
        page: pagination.page,
        limit: pagination.limit,
        total: result.total,
        pages: Math.ceil(result.total / pagination.limit),
      },
    });
});

router.get('/users/:id', async (req: Request, res: Response) => {
  const user = await userService.getUserById(req.params.id);

  if (!user) {
    return res.status(404).json({
      type: 'https://api.example.com/errors/not-found',
      title: 'User Not Found',
      status: 404,
      detail: `User ${req.params.id} does not exist`,
      instance: req.path,
    });
  }

  res.set('Cache-Control', 'private, max-age=300').status(200).json(user);
});

// Spring Boot
@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping
    public ResponseEntity<PagedResponse<User>> listUsers(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "20") int limit,
            @RequestParam(defaultValue = "createdAt") String sort,
            @RequestParam(defaultValue = "desc") String order,
            @RequestParam(required = false) String role) {

        int safeLimit = Math.min(limit, 100);
        UserFilters filters = UserFilters.builder().role(role).build();
        PageRequest pageable = PageRequest.of(page - 1, safeLimit,
                Sort.by(Sort.Direction.fromString(order), sort));

        Page<User> result = userService.listUsers(filters, pageable);

        PagedResponse<User> body = PagedResponse.<User>builder()
                .data(result.getContent())
                .pagination(PaginationMeta.of(page, safeLimit, result.getTotalElements()))
                .build();

        return ResponseEntity.ok()
                .header("Cache-Control", "private, max-age=60")
                .header("X-Total-Count", String.valueOf(result.getTotalElements()))
                .body(body);
    }

    @GetMapping("/{id}")
    public ResponseEntity<?> getUser(@PathVariable String id) {
        return userService.getUserById(id)
                .map(user -> ResponseEntity.ok()
                        .header("Cache-Control", "private, max-age=300")
                        .body((Object) user))
                .orElse(ResponseEntity.status(404).body(Map.of(
                        "type", "https://api.example.com/errors/not-found",
                        "title", "User Not Found",
                        "status", 404,
                        "detail", "User " + id + " does not exist")));
    }
}

# FastAPI
from fastapi import APIRouter, Query, HTTPException
from typing import Optional
from models import User, PagedResponse, PaginationMeta

router = APIRouter(prefix="/users")

@router.get("", response_model=PagedResponse[User])
async def list_users(
    page: int = Query(1, ge=1),
    limit: int = Query(20, ge=1, le=100),
    sort: str = Query("created_at"),
    order: str = Query("desc", pattern="^(asc|desc)$"),
    role: Optional[str] = None,
):
    filters = {"role": role} if role else {}
    result = await user_service.list_users(filters, page, limit, sort, order)

    return PagedResponse(
        data=result.users,
        pagination=PaginationMeta(
            page=page,
            limit=limit,
            total=result.total,
            pages=-(-result.total // limit),  # ceiling division
        ),
    )

@router.get("/{user_id}", response_model=User)
async def get_user(user_id: str):
    user = await user_service.get_user_by_id(user_id)
    if not user:
        raise HTTPException(
            status_code=404,
            detail={
                "type": "https://api.example.com/errors/not-found",
                "title": "User Not Found",
                "status": 404,
                "detail": f"User {user_id} does not exist",
            },
        )
    return user

// ASP.NET Core
[ApiController]
[Route("users")]
public class UsersController : ControllerBase
{
    [HttpGet]
    [ResponseCache(Duration = 60, Location = ResponseCacheLocation.Client)]
    public async Task<IActionResult> ListUsers(
        [FromQuery] int page = 1,
        [FromQuery] int limit = 20,
        [FromQuery] string sort = "createdAt",
        [FromQuery] string order = "desc",
        [FromQuery] string? role = null)
    {
        var safeLimit = Math.Min(limit, 100);
        var filters = new UserFilters { Role = role };
        var result = await _userService.ListUsersAsync(filters, page, safeLimit, sort, order);

        Response.Headers["X-Total-Count"] = result.Total.ToString();
        return Ok(new
        {
            data = result.Users,
            pagination = new { page, limit = safeLimit, total = result.Total, pages = (int)Math.Ceiling((double)result.Total / safeLimit) }
        });
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetUser(string id)
    {
        var user = await _userService.GetUserByIdAsync(id);
        if (user == null)
            return NotFound(new { type = "https://api.example.com/errors/not-found", title = "User Not Found", status = 404, detail = $"User {id} does not exist" });

        Response.Headers["Cache-Control"] = "private, max-age=300";
        return Ok(user);
    }
}

router.post('/users', async (req: Request, res: Response) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json({
      type: 'https://api.example.com/errors/unprocessable-entity',
      title: 'Validation Failed',
      status: 422,
      detail: 'One or more fields failed validation',
      errors: parsed.error.flatten().fieldErrors,
      instance: req.path,
    });
  }

  try {
    const user = await userService.createUser(parsed.data);
    res
      .status(201)
      .set('Location', `/users/${user.id}`)
      .json(user);
  } catch (err) {
    if (err instanceof DuplicateEmailError) {
      return res.status(409).json({
        type: 'https://api.example.com/errors/conflict',
        title: 'Email Already Registered',
        status: 409,
        detail: `The email ${parsed.data.email} is already in use`,
        instance: req.path,
      });
    }
    throw err;
  }
});

@PostMapping
public ResponseEntity<?> createUser(@Valid @RequestBody CreateUserRequest body,
        BindingResult binding, HttpServletRequest request) {
    if (binding.hasErrors()) {
        Map<String, List<String>> fieldErrors = binding.getFieldErrors().stream()
                .collect(Collectors.groupingBy(FieldError::getField,
                        Collectors.mapping(FieldError::getDefaultMessage, Collectors.toList())));
        return ResponseEntity.status(422).body(Map.of(
                "type", "https://api.example.com/errors/unprocessable-entity",
                "title", "Validation Failed",
                "status", 422,
                "errors", fieldErrors));
    }

    try {
        User user = userService.createUser(body);
        URI location = URI.create("/users/" + user.getId());
        return ResponseEntity.created(location).body(user);
    } catch (DuplicateEmailException e) {
        return ResponseEntity.status(409).body(Map.of(
                "type", "https://api.example.com/errors/conflict",
                "title", "Email Already Registered",
                "status", 409,
                "detail", e.getMessage()));
    }
}

from fastapi import APIRouter, Request
from fastapi.responses import JSONResponse
from pydantic import BaseModel, EmailStr

class CreateUserRequest(BaseModel):
    name: str
    email: EmailStr
    role: str = "user"

@router.post("", status_code=201)
async def create_user(body: CreateUserRequest, request: Request):
    try:
        user = await user_service.create_user(body.dict())
        return JSONResponse(
            status_code=201,
            content=user.dict(),
            headers={"Location": f"/users/{user.id}"},
        )
    except DuplicateEmailError:
        return JSONResponse(status_code=409, content={
            "type": "https://api.example.com/errors/conflict",
            "title": "Email Already Registered",
            "status": 409,
            "detail": f"The email {body.email} is already in use",
        })

[HttpPost]
public async Task<IActionResult> CreateUser([FromBody] CreateUserRequest body)
{
    if (!ModelState.IsValid)
    {
        var errors = ModelState.ToDictionary(
            k => k.Key,
            v => v.Value!.Errors.Select(e => e.ErrorMessage).ToList());
        return UnprocessableEntity(new { type = "https://api.example.com/errors/unprocessable-entity", title = "Validation Failed", status = 422, errors });
    }

    try
    {
        var user = await _userService.CreateUserAsync(body);
        return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user);
    }
    catch (DuplicateEmailException ex)
    {
        return Conflict(new { type = "https://api.example.com/errors/conflict", title = "Email Already Registered", status = 409, detail = ex.Message });
    }
}

// PUT — full replacement
router.put('/users/:id', async (req: Request, res: Response) => {
  const parsed = replaceUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json({ type: 'https://api.example.com/errors/unprocessable-entity', title: 'Validation Failed', status: 422, errors: parsed.error.flatten().fieldErrors });
  }

  const updated = await userService.replaceUser(req.params.id, parsed.data);
  if (!updated) return res.status(404).json({ type: 'https://api.example.com/errors/not-found', title: 'User Not Found', status: 404 });
  res.status(200).json(updated);
});

// PATCH — partial update (JSON Merge Patch)
router.patch('/users/:id', async (req: Request, res: Response) => {
  const parsed = patchUserSchema.safeParse(req.body);   // all fields optional
  if (!parsed.success) {
    return res.status(422).json({ type: 'https://api.example.com/errors/unprocessable-entity', title: 'Validation Failed', status: 422, errors: parsed.error.flatten().fieldErrors });
  }

  const updated = await userService.patchUser(req.params.id, parsed.data);
  if (!updated) return res.status(404).json({ type: 'https://api.example.com/errors/not-found', title: 'User Not Found', status: 404 });
  res.status(200).json(updated);
});

// PUT
@PutMapping("/{id}")
public ResponseEntity<?> replaceUser(@PathVariable String id,
        @Valid @RequestBody ReplaceUserRequest body) {
    return userService.replaceUser(id, body)
            .map(u -> ResponseEntity.ok((Object) u))
            .orElse(ResponseEntity.status(404).body(Map.of(
                    "type", "https://api.example.com/errors/not-found",
                    "title", "User Not Found", "status", 404)));
}

// PATCH
@PatchMapping(value = "/{id}", consumes = "application/merge-patch+json")
public ResponseEntity<?> patchUser(@PathVariable String id,
        @RequestBody Map<String, Object> patch) {
    return userService.patchUser(id, patch)
            .map(u -> ResponseEntity.ok((Object) u))
            .orElse(ResponseEntity.status(404).body(Map.of(
                    "type", "https://api.example.com/errors/not-found",
                    "title", "User Not Found", "status", 404)));
}

from typing import Optional
from pydantic import BaseModel

class ReplaceUserRequest(BaseModel):
    name: str
    email: EmailStr
    role: str
    address: str
    phone: str

class PatchUserRequest(BaseModel):
    name: Optional[str] = None
    email: Optional[EmailStr] = None
    role: Optional[str] = None
    address: Optional[str] = None
    phone: Optional[str] = None

@router.put("/{user_id}")
async def replace_user(user_id: str, body: ReplaceUserRequest):
    updated = await user_service.replace_user(user_id, body.dict())
    if not updated:
        raise HTTPException(status_code=404, detail={"title": "User Not Found", "status": 404})
    return updated

@router.patch("/{user_id}")
async def patch_user(user_id: str, body: PatchUserRequest):
    # exclude_unset preserves JSON Merge Patch semantics
    patch = body.dict(exclude_unset=True)
    updated = await user_service.patch_user(user_id, patch)
    if not updated:
        raise HTTPException(status_code=404, detail={"title": "User Not Found", "status": 404})
    return updated

// PUT
[HttpPut("{id}")]
public async Task<IActionResult> ReplaceUser(string id, [FromBody] ReplaceUserRequest body)
{
    if (!ModelState.IsValid) return UnprocessableEntity(ModelState);
    var updated = await _userService.ReplaceUserAsync(id, body);
    return updated != null ? Ok(updated) : NotFound(new { title = "User Not Found", status = 404 });
}

// PATCH
[HttpPatch("{id}")]
public async Task<IActionResult> PatchUser(string id, [FromBody] JsonElement patch)
{
    // Use JsonMergePatch or Microsoft.AspNetCore.JsonPatch
    var updated = await _userService.PatchUserAsync(id, patch);
    return updated != null ? Ok(updated) : NotFound(new { title = "User Not Found", status = 404 });
}

router.delete('/users/:id', async (req: Request, res: Response) => {
  const exists = await userService.userExists(req.params.id);
  if (!exists) {
    return res.status(404).json({
      type: 'https://api.example.com/errors/not-found',
      title: 'User Not Found',
      status: 404,
      detail: `User ${req.params.id} does not exist`,
    });
  }

  await userService.softDeleteUser(req.params.id);   // sets deletedAt
  res.status(204).send();
});

@DeleteMapping("/{id}")
public ResponseEntity<?> deleteUser(@PathVariable String id) {
    if (!userService.userExists(id)) {
        return ResponseEntity.status(404).body(Map.of(
                "type", "https://api.example.com/errors/not-found",
                "title", "User Not Found", "status", 404,
                "detail", "User " + id + " does not exist"));
    }
    userService.softDeleteUser(id);
    return ResponseEntity.noContent().build();
}

@router.delete("/{user_id}", status_code=204)
async def delete_user(user_id: str):
    exists = await user_service.user_exists(user_id)
    if not exists:
        raise HTTPException(status_code=404, detail={
            "type": "https://api.example.com/errors/not-found",
            "title": "User Not Found",
            "status": 404,
        })
    await user_service.soft_delete_user(user_id)

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteUser(string id)
{
    if (!await _userService.UserExistsAsync(id))
        return NotFound(new { type = "https://api.example.com/errors/not-found", title = "User Not Found", status = 404, detail = $"User {id} does not exist" });

    await _userService.SoftDeleteUserAsync(id);
    return NoContent();
}

// TypeScript — Express with Zod validation
import express, { Router, Request, Response, NextFunction } from 'express';
import { z } from 'zod';

const router = Router();

const createUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(['user', 'admin']).default('user'),
});

const patchUserSchema = createUserSchema.partial();

// GET /users — list with filtering, sorting, cursor pagination
router.get('/', async (req: Request, res: Response) => {
  const { limit = '25', after, role, q } = req.query;
  const safeLimit = Math.min(Number(limit), 100);

  const cursor = after ? Buffer.from(String(after), 'base64').toString() : undefined;
  const filters = {
    ...(role && { role: String(role) }),
    ...(q && { search: String(q) }),
    ...(cursor && { afterId: cursor }),
  };

  const users = await userService.listUsers(filters, safeLimit + 1);
  const hasMore = users.length > safeLimit;
  const page = hasMore ? users.slice(0, safeLimit) : users;
  const nextCursor = hasMore ? Buffer.from(page[page.length - 1].id).toString('base64') : null;

  res.status(200).json({
    data: page,
    pagination: {
      limit: safeLimit,
      hasMore,
      cursors: { after: nextCursor },
      ...(nextCursor && { next: `/users?limit=${safeLimit}&after=${nextCursor}` }),
    },
  });
});

// POST /users
router.post('/', async (req: Request, res: Response) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json({ type: 'https://api.example.com/errors/unprocessable-entity', title: 'Validation Failed', status: 422, errors: parsed.error.flatten().fieldErrors, instance: req.path });
  }
  const user = await userService.createUser(parsed.data);
  res.status(201).set('Location', `/users/${user.id}`).json(user);
});

// PATCH /users/:id
router.patch('/:id', async (req: Request, res: Response) => {
  const parsed = patchUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json({ type: 'https://api.example.com/errors/unprocessable-entity', title: 'Validation Failed', status: 422, errors: parsed.error.flatten().fieldErrors });
  }
  const updated = await userService.patchUser(req.params.id, parsed.data);
  if (!updated) return res.status(404).json({ type: 'https://api.example.com/errors/not-found', title: 'User Not Found', status: 404 });
  res.status(200).json(updated);
});

// DELETE /users/:id
router.delete('/:id', async (req: Request, res: Response) => {
  const deleted = await userService.softDeleteUser(req.params.id);
  if (!deleted) return res.status(404).json({ type: 'https://api.example.com/errors/not-found', title: 'User Not Found', status: 404 });
  res.status(204).send();
});

// Global error handler
app.use((err: Error, req: Request, res: Response, _next: NextFunction) => {
  console.error(err);
  res.status(500).json({ type: 'https://api.example.com/errors/internal', title: 'Internal Server Error', status: 500 });
});

// Java — Spring Boot with Bean Validation
@RestController
@RequestMapping("/v1/users")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    @GetMapping
    public ResponseEntity<Map<String, Object>> listUsers(
            @RequestParam(defaultValue = "25") int limit,
            @RequestParam(required = false) String after,
            @RequestParam(required = false) String role,
            @RequestParam(required = false) String q) {

        int safeLimit = Math.min(limit, 100);
        String cursor = after != null
                ? new String(Base64.getDecoder().decode(after))
                : null;

        UserFilters filters = UserFilters.builder()
                .role(role).search(q).afterId(cursor).build();

        List<User> users = userService.listUsers(filters, safeLimit + 1);
        boolean hasMore = users.size() > safeLimit;
        List<User> page = hasMore ? users.subList(0, safeLimit) : users;
        String nextCursor = hasMore
                ? Base64.getEncoder().encodeToString(page.get(page.size() - 1).getId().getBytes())
                : null;

        Map<String, Object> pagination = new LinkedHashMap<>();
        pagination.put("limit", safeLimit);
        pagination.put("hasMore", hasMore);
        if (nextCursor != null) {
            pagination.put("cursors", Map.of("after", nextCursor));
            pagination.put("next", "/v1/users?limit=" + safeLimit + "&after=" + nextCursor);
        }

        return ResponseEntity.ok(Map.of("data", page, "pagination", pagination));
    }

    @PostMapping
    public ResponseEntity<?> createUser(@Valid @RequestBody CreateUserRequest body) {
        User user = userService.createUser(body);
        return ResponseEntity.status(201)
                .header("Location", "/v1/users/" + user.getId())
                .body(user);
    }

    @PatchMapping(value = "/{id}", consumes = "application/merge-patch+json")
    public ResponseEntity<?> patchUser(@PathVariable String id,
            @RequestBody Map<String, Object> patch) {
        return userService.patchUser(id, patch)
                .map(u -> ResponseEntity.ok((Object) u))
                .orElse(ResponseEntity.status(404).body(Map.of(
                        "type", "https://api.example.com/errors/not-found",
                        "title", "User Not Found", "status", 404)));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<?> deleteUser(@PathVariable String id) {
        if (!userService.softDeleteUser(id))
            return ResponseEntity.status(404).body(Map.of(
                    "type", "https://api.example.com/errors/not-found",
                    "title", "User Not Found", "status", 404));
        return ResponseEntity.noContent().build();
    }
}

# Python — FastAPI with Pydantic v2
from fastapi import APIRouter, Query, HTTPException, Response
from fastapi.responses import JSONResponse
from pydantic import BaseModel, EmailStr
from typing import Optional
import base64

router = APIRouter(prefix="/v1/users", tags=["users"])

class CreateUserRequest(BaseModel):
    name: str
    email: EmailStr
    role: str = "user"

class PatchUserRequest(BaseModel):
    name: Optional[str] = None
    email: Optional[EmailStr] = None
    role: Optional[str] = None

def encode_cursor(value: str) -> str:
    return base64.b64encode(value.encode()).decode()

def decode_cursor(cursor: str) -> str:
    return base64.b64decode(cursor.encode()).decode()

@router.get("")
async def list_users(
    limit: int = Query(25, ge=1, le=100),
    after: Optional[str] = None,
    role: Optional[str] = None,
    q: Optional[str] = None,
):
    cursor_id = decode_cursor(after) if after else None
    filters = {"role": role, "search": q, "after_id": cursor_id}
    users = await user_service.list_users(filters, limit + 1)

    has_more = len(users) > limit
    page = users[:limit]
    next_cursor = encode_cursor(page[-1].id) if has_more else None

    return {
        "data": page,
        "pagination": {
            "limit": limit,
            "hasMore": has_more,
            "cursors": {"after": next_cursor} if next_cursor else {},
            **({"next": f"/v1/users?limit={limit}&after={next_cursor}"} if next_cursor else {}),
        },
    }

@router.post("", status_code=201)
async def create_user(body: CreateUserRequest, response: Response):
    user = await user_service.create_user(body.model_dump())
    response.headers["Location"] = f"/v1/users/{user.id}"
    return user

@router.patch("/{user_id}")
async def patch_user(user_id: str, body: PatchUserRequest):
    patch = body.model_dump(exclude_unset=True)
    updated = await user_service.patch_user(user_id, patch)
    if not updated:
        raise HTTPException(status_code=404, detail={"type": "https://api.example.com/errors/not-found", "title": "User Not Found", "status": 404})
    return updated

@router.delete("/{user_id}", status_code=204)
async def delete_user(user_id: str):
    deleted = await user_service.soft_delete_user(user_id)
    if not deleted:
        raise HTTPException(status_code=404, detail={"type": "https://api.example.com/errors/not-found", "title": "User Not Found", "status": 404})

// C# — ASP.NET Core with FluentValidation
[ApiController]
[Route("v1/users")]
public class UsersController : ControllerBase
{
    private readonly IUserService _userService;
    public UsersController(IUserService userService) => _userService = userService;

    [HttpGet]
    public async Task<IActionResult> ListUsers(
        [FromQuery] int limit = 25,
        [FromQuery] string? after = null,
        [FromQuery] string? role = null,
        [FromQuery] string? q = null)
    {
        var safeLimit = Math.Min(limit, 100);
        var cursor = after != null
            ? System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(after))
            : null;

        var filters = new UserFilters { Role = role, Search = q, AfterId = cursor };
        var users = await _userService.ListUsersAsync(filters, safeLimit + 1);

        var hasMore = users.Count > safeLimit;
        var page = hasMore ? users.Take(safeLimit).ToList() : users;
        var nextCursor = hasMore
            ? Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(page.Last().Id))
            : null;

        return Ok(new
        {
            data = page,
            pagination = new
            {
                limit = safeLimit,
                hasMore,
                cursors = nextCursor != null ? new { after = nextCursor } : null,
                next = nextCursor != null ? $"/v1/users?limit={safeLimit}&after={nextCursor}" : null
            }
        });
    }

    [HttpPost]
    public async Task<IActionResult> CreateUser([FromBody] CreateUserRequest body)
    {
        if (!ModelState.IsValid) return UnprocessableEntity(ModelState);
        var user = await _userService.CreateUserAsync(body);
        return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user);
    }

    [HttpPatch("{id}")]
    public async Task<IActionResult> PatchUser(string id, [FromBody] JsonElement patch)
    {
        var updated = await _userService.PatchUserAsync(id, patch);
        return updated != null ? Ok(updated) : NotFound(new { type = "https://api.example.com/errors/not-found", title = "User Not Found", status = 404 });
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteUser(string id)
    {
        var deleted = await _userService.SoftDeleteUserAsync(id);
        return deleted ? NoContent() : NotFound(new { type = "https://api.example.com/errors/not-found", title = "User Not Found", status = 404 });
    }
}