Back to blog

Blackbox Protocol: Rethinking How We Build APIs

·4 min read
typescriptapidevelopmentprojectwork-in-progress

I've been working on something that keeps me up at night. Not because it's broken, but because I can't stop thinking about it.

The Problem That Wouldn't Leave Me Alone

Every time I build something with an API, the same frustration surfaces. You get a list of endpoints. Maybe some documentation. And then... you're on your own.

Take a shopping site. You need to:

  • Retrieve products
  • Add them to a cart
  • Submit an order
  • Process payment
  • Get confirmation

The API gives you the endpoints. But the orchestration the how and when and in what order that logic ends up scattered. Duplicated across web and mobile. Hardcoded in UI components. Brittle when requirements change.

APIs don't tell you how to use them. They're just endpoints.

What If Workflows Came First?

This is the idea behind Blackbox Protocol. Instead of shipping 47 API endpoints and hoping developers figure it out, you ship a workflow file that orchestrates everything. The UI just asks: "What can I do right now?"

Three primitives. That's the entire API:

blackbox.can(); // What can I do right now?
blackbox.do(); // Do it
blackbox.where(); // Where am I?

The workflow is the documentation. The workflow is the orchestration. The workflow is the API.

The Leisure Suit Larry Moment

Remember text adventures? That conversational interface where you'd type "look" and the game would tell you where you were, what you could do?

> look
You are in the hotel lobby.

> possible actions
- Go to elevator
- Talk to receptionist
- Check inventory

> go to elevator

That's Blackbox. Replace "look" with where(). Replace "possible actions" with can(). Replace "go to elevator" with do('GO_ELEVATOR').

Modern UIs are just fancy Larry games. We forgot that.

Protocol Over Implementation

Here's where it gets interesting. Programs never contain URLs, HTTP methods, or GraphQL queries. That's all implementation detail. Programs only describe:

  • What operations are needed
  • What data flows through
  • What transitions are possible
  • What validations are required

The actual backend calls? Those live in "plugs" swappable at runtime. REST today, GraphQL tomorrow, mock data for testing. Same program, different plugs.

// Program (pure protocol - what)
operations: {
  searchProducts: {
    input: { query: 'string' },
    output: { products: 'Product[]' }
  }
}
 
// Plug (pure implementation - how)
plugs: {
  searchProducts: async (data, input) => {
    return fetch('/api/products?q=' + input.query).then(r => r.json());
  }
}

Discovery Over Documentation

Instead of writing API docs and hoping developers read them, you ship a .program.json file. UIs query what's possible. Actions appear automatically. Changes propagate instantly.

session.can();
// → ['SEARCH', 'ADD_TO_CART', 'CHECKOUT']

The UI can auto-generate:

{
  actions.map((action) => <button onClick={() => session.do(action)}>{action.label}</button>);
}

No hardcoded navigation. No magic strings. Just discovery.

Still Building

This is a work in progress. The proof of concept works. The philosophy feels right. But there's more to figure out edge cases, real-world testing, the inevitable "I didn't think of that" moments.

The goal is ambitious: developers stop writing API docs because they ship programs instead. UIs stop hardcoding workflows because they just ask what's possible. Backend changes don't break clients because plugs are swappable.

One program that runs everywhere: web, mobile, CLI, AI agents. Against any backend: REST, GraphQL, mocked data, local storage.

The Bigger Thought

Libraries come and go. Protocols last forever.

Blackbox isn't trying to be another state machine library. It's trying to be a way of thinking about workflows where the protocol is language-agnostic, the files are portable, and discovery replaces documentation.

Maybe it works. Maybe it doesn't. But the idea that APIs should tell you how to use them, that workflows should be first-class citizens, that UIs should discover rather than hardcode that feels like something worth exploring.

The cursor is blinking. The workflow is waiting. Let's see where this goes.

Follow along at github.com/alecorsino/blackbox