REST API class diagram
Controllers, services, and repositories.
This is the canonical shape of a REST backend: a controller that owns the HTTP surface, a service that owns the business logic, a repository that owns persistence, and the domain entity they all revolve around. The template draws one complete vertical slice — orders — with realistic method signatures at every layer.
Notice how the method names shift as you descend: the controller speaks HTTP (listOrders, createOrder), the service speaks domain (findAll, create), and the repository speaks storage (query, save). That vocabulary gradient is the pattern working as intended, and seeing it in a diagram makes layering violations easy to spot in review.
When to use this template
- Starting a new service — agree on the layering before the first file exists, so every resource that follows copies a deliberate structure instead of an accident.
- Onboarding backend engineers — one glance answers "where does validation go?" and "who is allowed to touch the database?" faster than reading three packages of source.
- Refactoring legacy code — draw the target architecture as a class diagram, then measure the current code against it. Arrows that would have to point upward mark the violations.
How to adapt it
Rename Order to your own resource and adjust the method lists to your actual endpoints, then extend the slice with whatever your stack adds:
- Add DTO classes (CreateOrderDto, OrderResponse) and connect them to the controller to document your request and response shapes.
- Introduce an interface for the repository (
<<interface>>in Mermaid) if you swap implementations between production and tests. - Attach cross-cutting collaborators — an EventPublisher or NotificationService hanging off the service layer.
Because visual edits regenerate clean Mermaid code, you can sketch the structure by dragging classes around and still commit a tidy text diagram next to the code it describes.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
classDiagram
class OrderController {
+listOrders() Order[]
+getOrder(id) Order
+createOrder(dto) Order
}
class OrderService {
+findAll() Order[]
+findById(id) Order
+create(dto) Order
}
class OrderRepository {
+query(filter) Order[]
+save(order) Order
}
class Order {
+String id
+String status
+Money total
+place()
+cancel()
}
OrderController --> OrderService
OrderService --> OrderRepository
OrderRepository --> Order
Frequently asked questions
- What is the controller-service-repository pattern?
- It's the standard layering for REST backends: controllers translate HTTP into method calls, services hold business logic, and repositories handle persistence. Each layer only talks to the one below it, which is exactly what the arrows in this diagram assert. The pattern appears under different names in Spring, NestJS, Laravel, and ASP.NET, but the shape is the same.
- How do I write a class diagram in Mermaid?
- Start with classDiagram, declare each class in a class Name block, and list members inside it — a plus sign marks public visibility, and a trailing type like Order[] declares the return type. Relationships go on their own lines: A --> B draws a directed association. This template shows all three pieces in about thirty lines.
- Should I diagram every class in my API or just one slice?
- One vertical slice. Diagramming a single resource — here, orders — from controller down to entity documents the pattern, and readers can infer that users and payments follow the same shape. A diagram with every class becomes a wall of boxes nobody maintains; a four-class slice stays accurate because it's cheap to update.
- What is the difference between an association and a dependency in a class diagram?
- An association (solid arrow, as used here) means one class holds a lasting reference to another — the controller keeps a service instance, typically injected via constructor. A dependency (dashed arrow, ..> in Mermaid) is a weaker, transient use, like accepting a type as a parameter. Swap the arrows if your layers only touch briefly rather than hold references.