The Negative API: emitempty and the Art of Returning Nothing on Purpose

Every API you've ever used follows the same paradigm: you ask for something, and the API gives it to you. GET /users/42 returns user 42. GET /products?category=shoes returns shoes. It's intuitive. It's boring. And it's fundamentally limited by a positional worldview that treats data as something you retrieve.

What if data is something you eliminate?

Introducing emitempty — a Negative API framework where every endpoint returns not what you asked for, but what you didn't ask for. The data you want is defined by the absence of everything else.

"Michelangelo said he sculpted David by removing everything that wasn't David. We apply the same principle to JSON responses."

Core Concept: The Complement Endpoint

In a traditional API, GET /users returns all users. In emitempty, GET /not/users returns everything in the database that is not a user. Products, orders, logs, system config, audit trails — all of it. Your users are whatever's missing from the response.

GET /not/users HTTP/1.1
Host: api.example.com

// Response: 200 OK
// Content-Length: 847293847
{
  "complement": [
    { "type": "product", "id": 1, "name": "Widget A" },
    { "type": "product", "id": 2, "name": "Widget B" },
    // ... 2.3 million more records ...
    { "type": "audit_log", "id": 9847293, "action": "someone queried /not/users again" }
  ],
  "_meta": {
    "what_you_wanted": "users",
    "what_you_got": "everything else",
    "sorry": true
  }
}

The emitempty Endpoint

The crown jewel of the Negative API is the /emitempty endpoint. It returns nothing. Not "no results found" nothing — actual nothing. The response body is empty. The Content-Length is 0. The HTTP status is 204 No Content. The server processes the request, queries the database, builds a complete response, and then throws it away before sending it.

GET /emitempty HTTP/1.1
Host: api.example.com

// Response: 204 No Content
// X-Data-Existed: true
// X-Data-Returned: false
// X-Server-Feelings: conflicted

The custom headers confirm that data existed and was deliberately not returned. This is different from a 404, where the data never existed. In emitempty, the data is real. You just can't have it. The server knows what you wanted. It chose not to comply.

Practical Applications

Authentication by Elimination

Traditional auth: send credentials, get a token. Negative auth: call GET /not/unauthorized-resources. The response contains every resource you don't have access to. Whatever's missing from the response is yours. This has the side effect of revealing the existence of every protected resource in the system, which our security team describes as "suboptimal."

Search by Exclusion

Looking for a specific product? Don't search for it. Call GET /not/products?not-name=Widget+A, which returns all products that are not named Widget A. If the response contains everything except Widget A, then Widget A exists. If the response contains Widget A, then Widget A doesn't exist, because the Negative API has paradoxed itself and Widget A is now in a superposition.

Deletion

In a positive API, you DELETE /users/42 to remove a user. In emitempty, you POST /users with every user except user 42. The system diffs the new state against the old state and infers the deletion. This requires sending the entire user database minus one record in the request body. For our production database of 340,000 users, a single delete request is approximately 1.4GB. We're working on pagination.

Benchmarks

• Average response size: 847MB (for a query that would return 3 records in a positive API)
• Average response time: 34 seconds (most of this is serializing the complement set)
• /emitempty response time: 0.003ms (fastest endpoint we've ever built; returning nothing is extremely efficient)
• Client-side computation to extract actual data: 2-4 minutes depending on complement set size
• Bandwidth consumed per query: roughly equivalent to streaming a movie
• Engineers who understand why this exists: 1 (me, and I'm having doubts)

emitempty is available as a middleware for Express and Rails. The npm package has 3 downloads, all from me, from three different computers, because I wanted the download graph to show growth.