Versioning

Two version numbers describe this API, and they answer different questions.

/v1 in the path is the interface. It changes only when something already documented stops being true, and this page is what that means in practice.

The number in /v1/health, in the index at the base URL, and in the OpenAPI document’s info.version is the implementation. It moves with every release and follows semantic versioning. Read it when you want to know which build answered you; do not branch on it.

A third number is on the site rather than in the API: the one beside the wordmark on the home page is the OpenDice release these pages document. It moves when the package does, which need not be when the API does, and it is not something the API reports about itself.

What v1 promises

• The endpoints keep their paths and methods. GET /v1/roll, POST /v1/roll, POST /v1/roll/batch and GET /v1/health will not move or change verb.
• A field keeps its name, its type and its meaning. If keptFlags is a list of booleans aligned to results today, it is that for as long as v1 is.
• Error code values are stable. A code will not be renamed, and will not quietly come to mean something else.
• A status carries only the codes documented against it. A 429 is rate_limited; the OpenAPI document says so per status, which is what lets a generated client narrow the type.

What may change inside v1

• New fields may appear in a response. Ignore the ones you do not recognise rather than failing on them. Nothing you already read will be removed to make room.
• New error codes may be added to a status. Handle the codes you care about and treat an unfamiliar one as a plain failure of its status, rather than exhaustively matching every code and breaking on the first addition.
• Every message may be reworded. It is written for a person to read. Match on code, never on the text beside it.
• The limits may move. Both the limits page and the OpenAPI document are generated from the code that enforces them, so they are the authority rather than anything you have written down.
• The rate limit may be tuned. It is a guard against abuse, not a quota, and it was never a number to budget against — see the limits page for why.

Deprecations

Something on its way out keeps working while it is on its way out. 1d20adv is the current example: a count of 1 still rolls, and still rolls two dice, but 2d20adv is the formula it means and a future version will refuse the shorter one.

Notice arrives differently depending on how you roll. The package warns once per formula shape on the console. Over HTTP that warning is written to this service’s logs rather than into your response, so for API callers this documentation is the only notice a deprecation gets. If you generate formulas rather than accepting them from people, it is worth re-reading the grammar when the implementation version changes.

What is not coming

Two things are settled rather than merely absent.

The random source stays closed. The package accepts an injectable one for testing; the API does not expose it and never will. A result records what the dice showed and never where the numbers came from, so a caller-chosen source would let anyone pick their own results while the response still looked honest.

No game-system rules. Rollful knows what 4d6kh3 means and nothing about what you use it for. No character sheets, no system presets, no named rolls. That work belongs above this API, where it can differ per game without asking anyone’s permission.

How a breaking change would arrive

As /v2, on its own path, alongside /v1 rather than instead of it. Nothing in this document is changed by editing it — a promise withdrawn is a new version of the interface, which is what the number in the path is for.