Haskell API Project

A compact yet powerful backend API built using the Servant framework — designed to demonstrate how functional programming principles can drive scalable, type-safe, and maintainable REST architectures in Haskell.

This project is more than a minimal example — it’s a deep dive into the intersection of strong static typing and web service design, blending declarative API specification with real functional rigor.

---

⚙️ Overview

This project showcases how to:

• Use servant to define a type-safe REST API interface.
• Implement server-side logic with servant-server, ensuring full compile-time validation of routes.
• Test endpoints using hspec and servant-client, verifying both client and server consistency.
• Structure a Haskell backend project with clarity across src/, exe/, and test/ modules.

---

🧠 Why It Matters

In an era where backend systems are often fragile due to runtime inconsistencies, this project proves how Haskell’s type system guarantees correctness by construction. Each endpoint is both documentation and contract — impossible to misalign between server and client.

You’ll see how servant turns HTTP endpoints into compile-time verified types, making refactors safe and ensuring every route, parameter, and response is consistent.

---

📁 Project Structure

.
├── README.md                  # Project documentation
├── exe/Main.hs                # Application entry point (server startup)
├── src/App.hs                 # Core Servant API and business logic
├── package.yaml               # Build configuration and dependencies
├── stack.yaml / lock          # Stack project definitions
└── test/                      # End-to-end testing suite
    ├── AppSpec.hs             # Servant client-based API tests
    └── Spec.hs                # Entry point for hspec test execution

---

🚀 Getting Started

Setup and Run Tests

stack setup
stack test --fast

To execute the test suite faster during development:

chmod go-w .ghci .
stack exec ghci test/Spec.hs

Then at the GHCI prompt:

:main     -- run all tests
:r        -- reload code after editing
:main     -- re-run the test suite

---

🧩 Running the API Server

Run the backend:

stack exec example-servant-minimal

Then, query the running server:

curl localhost:3000/item

Expected output (example):

{"message": "Item retrieved successfully"}

---

🧱 Core Concepts Demonstrated

• Type-safe REST design with Servant
• Composable APIs that scale with project growth
• Functional purity & immutability in backend logic
• Test-driven development with Hspec + Servant Client
• Separation of concerns through modular project layout

---

🧭 Next Steps

• Extend API endpoints with authentication layers.
• Add persistent storage (e.g., PostgreSQL via persistent or beam).
• Deploy using Docker or Nix to containerize the service.
• Benchmark and profile with Criterion for performance tuning.

---

💡 Vision

This project represents the philosophy of correctness before runtime — where APIs are not just code but verified proofs of behavior. Built to show that backend engineering can be both elegant and bulletproof when guided by Haskell’s mathematical precision.