---
type: "article"
title: "API versioning without the tears"
summary: "Every versioning strategy is a way of choosing who you're going to disappoint. Choose deliberately."
newsletter: "API Bytes"
newsletter_handle: "api-bytes"
newsletter_url: "https://staging.in.usecommune.com/n/api-bytes"
author: "Fran Méndez (@fmvilas)"
published: "2026-08-03T08:30:00.000Z"
canonical_url: "https://staging.in.usecommune.com/n/api-bytes/a/versioning-without-tears"
markdown_url: "https://staging.in.usecommune.com/n/api-bytes/a/versioning-without-tears.md"
chat_url: "https://staging.in.usecommune.com/n/api-bytes/a/versioning-without-tears/chat"
body_source: "native"
likes: 7
replies: 1
body_words: 72
---

# API versioning without the tears

There is no versioning scheme that makes everyone happy. There are only schemes that make your future self slightly less miserable.

## The three honest options

- URL versioning: ugly, obvious, easy to route.
- Header versioning: clean URLs, invisible failures.
- No versioning, additive-only: the discipline tax you pay upfront.

> Pick the one your team will actually maintain in eighteen months, not the one that looks best in the RFC.

***

## Discussion (1 reply)

Numbering shows the reply tree: `2.1` is a reply to `2`. Message text is reproduced verbatim as posted.

### 1. Fran Méndez (@fmvilas) - 2026-09-02T20:14:15.099Z

> Pick the one your team will actually maintain in eighteen months

Absolutely 💯