Templates

Retire a template

Retire a template you published, so it stops resolving and stops counting against your ceiling.

WITH version this retires that one version. WITHOUT it, this retires EVERY version of the name — which is what “retire this template” means, and is deliberately not the read route’s “the newest”: a delete that quietly took the latest one would let a script walk backwards through a history it never asked about.

COMPUTERS ARE NOT AFFECTED. A computer is built from the IMAGE the ref resolved to and holds no reference to the document, so anything already running, stopped or suspended is untouched, before and after. What a retire breaks is resolution: a NEW create naming the ref is refused.

THE REF IS STILL SPOKEN FOR, AND STILL COUNTS ONCE. Retiring frees the row the templates ceiling counts; it does not free the name, and it does not reduce refs_claimed — the much larger ceiling on refs an account may ever claim. Publishing namespace/name@version again after retiring it is a 409, identical bytes included — a ref that resolves, then does not, then does again is worse than either. Publish the next version instead.

A ref that was never yours is a 403, including system. One you already retired is a 404 that says when it went. An API key confined to a workspace is a 403 whatever it names: retiring is for an account-wide key.

OMITTING version AND SENDING IT EMPTY ARE DIFFERENT. ?version= — which is what most clients send for an unset optional string — is a 400, not a request to retire the whole name. So is any value that is not a MAJOR.MINOR.PATCH. Leaving the parameter off the URL entirely is the only way to ask for every version.

Requires the member role or higher.

delete/templates/{namespace}/{name}

Request

  • Base URL: https://app.mandala.computer/api/v1
  • URL: https://app.mandala.computer/api/v1/templates/{namespace}/{name}
  • Auth: HTTP bearer

Path parameters

namespacestring required

Your account id, or system for the templates we publish.

namestring required

The template’s metadata.name — the part of the ref between the slash and the @.

Query parameters

versionstring

A specific MAJOR.MINOR.PATCH. Omit the parameter entirely to retire every version of this name; sending it empty or malformed is a 400.

Response

What went, what is left of the name, and how many templates the account now holds.

retiredstring[]

The refs that were retired, newest version first. Never empty — an empty retire is a 404.

retired_atstring

RFC 3339 timestamp. One value: everything in retired went in the same write.

versionsstring[]

The versions of this name still published, newest first. Empty means the name is gone — nothing resolves namespace/name any more.

templatesinteger

How many templates the account holds now. This is the number the per-account ceiling is against.

refs_claimedinteger

How many refs this account has ever claimed, live and retired together. It does NOT go down when you retire — a retired ref still counts, because it can never be published again — and there is a much larger ceiling on it than on templates. Reported here because this is the only place the two numbers can be seen moving differently.

Changes

No recorded changes to this operation across all 1 revision of this API.