Faker API

A developer-friendly fake REST API built with Spring Boot, designed to simulate realistic backend behavior such as delays, random errors, and forced HTTP statuses. This makes it ideal for frontend development, QA testing, error handling, and demo environments.

⚠️ This API is for testing and development only. Do NOT use in production.

---

✨ Features

• 🔁 Fake but realistic REST endpoints
• ⏱ Simulated response delays
• 💥 Random or forced HTTP errors
• 🎛 Per-request simulation control
• 📦 Consistent ApiResponse<T> wrapper
• 🧪 Ideal for frontend error/loading state testing
• 📖 Swagger-friendly & explicit behavior

---

🧠 Core Concept: Response Simulation

Instead of hiding fake behavior inside services, Faker API uses an explicit and opt-in simulation model.

Simulation is controlled via query parameters using SimulationOptions:

Parameter	Type	Description
delayMs	Integer	Artificial delay in milliseconds
errorRate	Double	Chance (0.0–1.0) to return a random error
forceStatus	Integer	Always return this HTTP status code

This logic is handled centrally by:

ResponseSimulator.simulateIfNeeded(simulationOptions)

If a simulated error occurs, the controller returns immediately.

---

📦 Example Endpoints

Get all roles

GET /api/roles

Get role details

GET /api/roles/{roleName}

Get role permissions

GET /api/roles/{roleName}/permissions

Check permission

POST /api/roles/check

Assign role

POST /api/roles/{roleName}/assign

Revoke role

DELETE /api/roles/{roleName}/revoke

---

🧪 Simulation Examples

Simulate slow backend

GET /api/roles?delayMs=2000

Simulate random errors (30% chance)

GET /api/roles?errorRate=0.3

Force a 500 error

GET /api/roles?forceStatus=500

Combine behaviors

GET /api/roles?delayMs=1500&errorRate=0.2

---

📄 Standard API Response

All endpoints return a consistent response format:

{
  "status": 200,
  "message": "Roles retrieved successfully",
  "data": [...],
  "count": 5
}

Error responses:

{
  "status": 500,
  "message": "Simulated error response (faker-api)",
  "error": "THIS IS A MOCK ERROR - DO NOT USE IN PRODUCTION"
}

---

🧩 Architecture Overview

• Controller layer

  • Handles HTTP requests
  • Applies response simulation
  • Returns ApiResponse<T>

• Service layer

  • Contains fake business logic
  • No delay/error logic

• Utility layer

  • ResponseSimulator (stateless)

---

🚀 Running the Project

./mvnw spring-boot:run

Default server:

http://localhost:8080

---

🧑‍💻 Intended Use Cases

• Frontend development without a real backend
• Testing loading states & retry logic
• Practicing error handling
• Demos & workshops
• Teaching REST API consumption

---

📜 License

MIT — free to use, modify, and extend.

---

🙌 Final Note

This project is intentionally transparent about its fake behavior. If an API lies to developers, it’s useless — Faker API doesn’t.

Happy testing 🚀