Beyond Functions: Why Your Next API Should Be Built on Verbs

As developers, we live in a world of functions. createUser(), sendInvoice(), updateStatus(). We write them, call them, and chain them together to build our applications. They are the fundamental building blocks of software. But what if this function-centric view is holding us back?

A simple function call is just an execution instruction. It lacks inherent business context, consistent logging, and a built-in audit trail. A single business process, like a user signing up, might trigger a cascade of disparate functions across multiple services, with its true meaning scattered and lost in the implementation details.

This is where a paradigm shift is needed. We need to move beyond simple functions and start thinking in terms of Verbs: clear, structured, and observable business actions. This is the core principle behind Verbs.do—treating your business operations as "Actions as Code."

The Problem with a Purely Functional View

When your business logic is only expressed as a collection of functions, you inevitably run into several challenges:

• Fragmented Processes: The logic for "Onboard New Client" might live partly in your user service, partly in your billing API, and partly in an email microservice. There's no single source of truth for what that business process entails.
• The Logging Nightmare: Logging is often an inconsistent afterthought. Different services log in different formats, and crucial contextual data is frequently missing. Piecing together what really happened during an incident becomes a painful forensic exercise.
• Audit-Readiness by Accident: When regulators or security auditors ask for a complete record of all actions performed by a specific user, can you provide it confidently? For many, this means a frantic scramble through disparate logs, hoping nothing was missed.

Enter the Verb: An Action as a First-Class Citizen

A Verb, in the context of Verbs.do, is not just a function. It's a standardized, formal definition of a business action. It encapsulates the what, who, why, and what happens next into a single, reusable unit.

Let's look at a simple, powerful example. Instead of just calling a function, you first define the action itself.

import { Verb } from 'verbs.do';

// Define a 'SignUp' action once
const signUp = new Verb({
  name: 'SignUp',
  description: 'A new user creates an account.',
  subject: { type: 'User' },
  properties: {
    email: { type: 'string', format: 'email' },
    password: { type: 'string', sensitive: true }
  },
  effects: [
    { name: 'CreateUserRecord' },
    { name: 'SendWelcomeEmail' }
  ]
});

This definition establishes a crystal-clear contract for a core business process. It declares the actor (subject), the data required (properties), and even the intended side-effects (effects) like creating a database record or sending an email. This is your single source of truth for what a "SignUp" is.

From Definition to Execution

Once defined, this Verb can be executed from anywhere in your application stack with a simple API call.

// Execute it anywhere in your application
await signUp.execute({
  subject: { id: 'user_123' },
  properties: {
    email: 'hello@example.com',
    password: 'a-secure-password'
  }
});

This is where the magic happens. This single execute call does more than just run code. It triggers a series of powerful, automated benefits that are nearly impossible to achieve consistently with standard function calls.

The Transformative Power of a Verb-Based Architecture

Adopting a Verb-centric approach fundamentally changes how you build and reason about your systems.

1. You Get a Perfect, Automatic Audit Trail

Every time a Verb is executed, Verbs.do creates a detailed, immutable log. This event record contains:

• The action that was performed (SignUp).
• Who performed it (subject: user_123).
• The data involved (with sensitive fields automatically handled).
• A precise timestamp.

Suddenly, you have a comprehensive audit trail and event stream of every significant action in your business. Answering "Who did what, and when?" goes from a week-long investigation to a simple query. This is a game-changer for compliance, security, and debugging.

2. Your Business Logic Becomes Clear and Centralized

Remember the effects array in our definition? That's your workflow automation blueprint. It explicitly states that a SignUp Verb should trigger CreateUserRecord and SendWelcomeEmail. The orchestration logic is co-located with the action's definition, not hidden in imperative code. This makes your business processes explicit, understandable, and easier to modify.

3. You Build a Self-Documenting System

Your code begins to speak the language of your business. Instead of developers trying to interpret what u_create_v2(p1, p2) does, they see SignUp.execute(). This approach, which we call Business-as-Code, creates a system where the operational intent is clear, observable, and directly tied to the code that implements it.

So, a Verb or a Function?

Think of it this way:

• A function call is like telling a worker, "Hammer this nail." It's a direct, low-level instruction.
• Executing a Verb is like handing them a signed and approved work order for "Install a new door." The work order specifies the task, the required materials, who authorized it, and ensures the job is logged as complete.

The Verb provides the structure, context, and observability that a simple function call lacks.

By elevating your actions from simple function calls to first-class Verbs, you're not just writing code—you're building a robust, auditable, and scalable system of record for everything that happens in your business.

Ready to turn your operations into code? Explore the Verbs.do API and see how you can define, execute, and log your business actions with unprecedented clarity.