In modern software development, we've become experts at modeling nouns. We define Users, Products, and Orders with meticulous care. Our REST APIs are elegant catalogs of these resources. But what about the actions that connect them? What about the verbs?
Think about a simple action: a User "following" another User. The logic for this single action is often scattered across your system. There's the frontend code that calls an endpoint, the backend controller that handles the request, a database service that creates the relationship, and maybe a separate job that sends a notification. This fragmentation is a breeding ground for inconsistency, bugs, and technical debt.
What if we could treat actions as first-class citizens in our codebase? What if we could define, manage, and execute any business interaction as a single, declarative piece of code? This is the core idea behind Business-as-Code, and it's set to change how we design our systems.
The traditional approach to APIs, centered around resources (nouns), implicitly forces business logic to live in the application layer. When a user clicks "Follow," the logic isn't packaged in a concept called "Follow"; it's hidden inside a POST /users/{id}/followers endpoint handler. If you need to trigger that same action from a background job or an admin panel, you either duplicate the logic or create complex internal service calls.
This is where a verb-driven architecture comes in. Instead of just modeling your data, you model the actions that can be performed on that data.
At Verbs.do, we formalize this concept into a powerful, executable primitive: the Verb.
A Verb is a declarative, code-based definition of an action that can be performed in your system. It clearly specifies the actor (subject), the entity being acted upon (object), and the effects that occur upon execution.
Let's look at what this means in practice. Here's how you can define a 'Follow' action as code:
import { Verb } from 'verbs.do';
// Define a 'Follow' action in your system
const follow = new Verb({
name: 'Follow',
subject: { type: 'User', description: 'The user who is following.' },
object: { type: 'User', description: 'The user being followed.' },
effects: [
{ type: 'createEdge', from: 'subject', to: 'object', label: 'follows' },
{ type: 'notify', user: 'object.id', message: '`{subject.name}` started following you.' }
]
});
// Now, any part of your system can execute this action
await follow.execute({ subjectId: 'user-123', objectId: 'user-456' });
In this single, self-contained definition, we've captured the entire business process: creating the relationship in the database and sending a notification. It's clear, auditable, and lives in one place.
Adopting an "Actions as Code" model unlocks a level of clarity and power that resource-based APIs can't match.
By codifying actions into Verbs, you pull your core business logic out of scattered services and controllers. The rules for an action are defined once and versioned like any other piece of software. This guarantees that every time a "Follow" action is executed—whether from your mobile app, web client, or a backend script—the exact same effects are triggered. This is the key to achieving true consistency and reliability.
This is where the paradigm truly shines. Verbs are designed to be composable building blocks. The effects of one Verb can easily trigger another, allowing you to construct complex, automated processes from simple, reusable actions.
Imagine a PurchaseProduct Verb. Its effects could trigger:
This allows you to build sophisticated and robust agentic workflows where the system intelligently carries out a chain of actions based on a single initial trigger, all while maintaining perfect auditability.
With a Verb-based system, the question is no longer "Which endpoint do I call?" but "Which action do I execute?". Once a Verb like follow is defined, anyone in your organization can execute it with a simple, unified API call: follow.execute(...). This single interface dramatically simplifies development for frontend engineers, backend developers, and a new generation of low-code/no-code tools that can now tap directly into your core business capabilities.
When an action is a piece of code, it gets all the benefits of modern software development practices. You can track changes in Git, perform code reviews on business logic modifications, and maintain a complete version history. Furthermore, since every execute call is a discrete event, the system can automatically generate a perfect audit log, answering "who did what to whom, and when?" for every interaction in your business.
The operations that define your business—subscribing, purchasing, approving, shipping—are all actions. It's time our software architecture reflected that reality.
By shifting our focus from modeling static resources to defining dynamic, executable verbs, we can build systems that are more robust, scalable, and easier to understand. Verbs.do is built to help you make this shift, translating your business operations into powerful, composable services.
Ready to stop scattering your logic and start defining your business as code? It's time to build your next API on Verbs.