We are typically taught to build API's around CRUD operations: POST /users GET /orders/{id} PUT /applications/{id} DELETE /products/{id} 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 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} 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 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 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. CRUD models data. Workflow APIs model behavior. 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. Workflow API Instead of PUT /loan/{id} PUT /loan/{id} We expose: POST /loan/{id}/submit POST /loan/{id}/approve POST /loan/{id}/cancel 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 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 Accept Loan Offer" 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 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} PUT /loan/{id} Hides the intent Instead: POST /loan/{id}/accept 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 POST /load/{id}/accept POST /application/{id}/submit They: Protect domain invariants Enforce valid transitions Align with business state machines 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 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 GET user/profile GET /user/applications/active GET /user/loans GET /user/payments/upcoming Client makes GET /user/dashboard GET /user/dashboard This endpoint: Aggregates multiple backend calls Optimizes network performance Exists for a specific client Encapsulates orchestration logic 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. 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 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 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 CRUD API Workflow API CRUD API CRUD API Workflow API Workflow API Resource-focused Action-focused Resource-focused Resource-focused Action-focused Action-focused Single-entity change Multi-step orchestration Single-entity change Single-entity change Multi-step orchestration Multi-step orchestration Data modeling Business modeling Data modeling Data modeling Business modeling Business modeling Simple DB mapping Domain-aware process Simple DB mapping Simple DB mapping Domain-aware process Domain-aware process Structure-oriented Intent-oriented Structure-oriented Structure-oriented Intent-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 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.
