We are typically taught to build API’s around CRUD operations:
- POST /users
- GET /orders/{id}
- PUT /applications/{id}
- DELETE /products/{id}
This may work well for basic systems, but it is hardly the case in practice. To explain the concept, let’s consider a scenario where a user is interacting with a fintech application and applying for a personal loan.
User makes these selections :
- Submits credit application
- Accept offer
- Sign offer
In real life, the backend doesn’t simply update one DB record. It validates business rules. updates multiple entities, triggers downstream services, emits events, and sometimes starts synchronous processing.
Yet we abstract all actions behind a single endpoint
PUT /entity/{id}
This confuses the user as he now no longer updates a table but triggers a business process. This is where Workflow API’s come in the picture.
The Limitations of CRUD
CRUD API’s assume simple one to one db interactions..
They work well when:
- The state is self-sufficient
- Update the field
- Delete the record
But they break down when:
- State transitions matter
- Business rules are complex
- Multiple services are involved
- Side effects must be coordinated
- Client flows drive orchestration
As systems scale, behavior becomes more important than structure.
CRUD models data.
Workflow APIs model behavior.
What Is a Workflow API?
A Workflow API is an endpoint designed around a business action rather than a raw resource update.
Instead of
PUT /loan/{id}
We expose:
POST /loan/{id}/submit
POST /loan/{id}/approve
POST /loan/{id}/cancel
These endpoints:
- Represent explicit domain intent
- Enforce state transitions
- Coordinate multiple operations
- Encapsulate business rules
- Make side effects intentional
They answer the question about what the user is trying to do rather than what table we are updating.
Identifying a Workflow
If an endpoint description goes like:
“When the user clicks this button, we validate X, update Y, notify Z, and trigger W…”
You are looking at a workflow rather than a CRUD operation.
For example, consider a fintech scenario:
User clicks the “Accept Loan Offer” button
Behind the scenes, the system will
- Validate the offer is still valid
- Lock the APR
- Update Loan status
- Generate loan docs
- Trigger e-sign workflow
- Notify risk systems
- Create funding schedule
Calling this:
PUT /loan/{id}
Hides the intent
Instead:
POST /loan/{id}/accept
Clearly reveals what is happening
Two Typical Types of Workflow API’s
1. Action-Based Workflow API’s
These represent domain state transitions.
Examples:
- POST /load/{id}/accept
- POST /application/{id}/submit
They:
- Protect domain invariants
- Enforce valid transitions
- Align with business state machines
These are common in systems using Domain Driven Design.
2. Client-Specific Workflow API’s
Sometimes an API exists purely to serve a specific client experience.
For example, a mobile dashboard might need:
- User profile
- Active incomplete applications
- Active loans
- Upcoming payments
Instead of four calls:
GET user/profile
GET /user/applications/active
GET /user/loans
GET /user/payments/upcoming
Client makes
GET /user/dashboard
This endpoint:
- Aggregates multiple backend calls
- Optimizes network performance
- Exists for a specific client
- Encapsulates orchestration logic
This pattern overlaps with the Backend-for-Frontend approach.
Why This Distinction Matters
When we design API’s around business intent:
- The contract becomes clearer
- State transitions are explicit
- Clients become simpler
- Backend logic becomes easier to reason about
- Hidden side effects are reduced.
Instead of leaking internal table structures to the public, we expose stable business actions.
Architectural Considerations
Workflow API’s introduce additional responsibilities.
Idempotency
If the client retries, should the workflow execute again?
Failure Handling
What happens if step 4 fails after steps 1–3 succeed?
Observability
Can you trace the workflow across services?
Transaction Boundaries
Is the process atomic or eventually consistent?
In distributed systems, workflow APIs often:
- Act as orchestrators
- Coordinate microservices
- Trigger events instead of direct DB writes
They are more complex than CRUD, but that complexity already exists. Workflow API’s simply make it explicit.
CRUD vs Workflow API’s
| CRUD API | Workflow API |
|—-|—-|
| Resource-focused | Action-focused |
| Single-entity change | Multi-step orchestration |
| Data modeling | Business modeling |
| Simple DB mapping | Domain-aware process |
| Structure-oriented | Intent-oriented |
Final Conclusion
CRUD is foundational. Every system needs it. Modern, production-grade systems are driven by workflows, not just table updates.
When an endpoint:
- Represents intent
- Drives state transitions
- Coordinates multiple systems
- Encapsulates domain rules
It’s not just an update endpoint. It’s a Workflow API.
Designing API’s around workflows instead of tables is one of the most important shifts in building real-world systems.
