Skip to content

Content Archives API

Install, remove, and inspect content archives over the API. For what an archive is, see Content Archives; for the drpcli workflow, see Build a Content Archive.

All calls live under /api/v3 and follow the DRP API conventions.

Feature gate

Content archives are newer than some endpoints your code will meet. Check GET /api/v3/info for content-archive-support in Features rather than comparing versions.

Listing

GET /api/v3/content_archives returns the installed archives — identity, the on-disk blob, and the embedded content layer's metadata and artifact manifest (Meta abridged here):

JSON
[
  {
    "Name": "my-content",
    "Version": "v1.0.0",
    "Source": "c2ce1ac3a017b09f4741413361ff2ff1b89b168b203bc1a7ed3dec9bfcda2592",
    "Meta": {
      "Name": "my-content",
      "Version": "v1.0.0",
      "Description": "Test content archive bundling a file artifact"
    },
    "Artifacts": {
      "files/hello.txt": {
        "source": "file://.../files/hello.txt",
        "install": [ { "action": "expose" } ]
      }
    }
  }
]

GET /api/v3/content_archives/sources returns the raw blob names instead — the storage view used by replication and backup. Source above is how a record maps to one of them.

Installing and removing

Every change goes through a transaction: start → add → commit. There is no single-shot install endpoint.

Text Only
POST   /api/v3/content_archives/update/start          -> token
POST   /api/v3/content_archives/update/:token/add     -> staged items
POST   /api/v3/content_archives/update/:token/commit  -> what changed
DELETE /api/v3/content_archives/update                 (abandon)

Four rules govern a session:

  • One at a time. A second start fails while a session is open. Cancel takes no token for the same reason.
  • It expires 30 minutes after the last operation.
  • It does not survive a restart or an HA leadership change. A batched update is deliberately failed rather than resumed across either.
  • An abandoned session blocks the next one until it expires, so cancel on every error path.

/add takes the file as the POST body and returns the records the endpoint staged for it. It accepts a content bundle (JSON or YAML) or a plugin provider as well as a .drpca — those are converted to archives on upload. Anything else is rejected.

/commit takes the staged records plus a list of names to remove, and applies them as one transaction. It waits for artifact replication to reach a safe point, rebuilds and consistency-checks the datastack, then switches to it. The response reports every change made:

JSON
[
  {
    "Name": "my-content",
    "Op": "add",
    "Path": "c2ce1ac3a017b09f4741413361ff2ff1b89b168b203bc1a7ed3dec9bfcda2592",
    "Version": "v1.0.0"
  }
]

A list, not one result, because a commit can touch several archives — one file may carry more than one, and replacing a version reports the removal alongside the addition. Removals carry only Name and Op.

Commit answers 503 Service Unavailable with Retry-After when the endpoint is not ready; retry rather than treating it as failure.

GET /api/v3/content_archives/update/status describes an open session — its token, who opened it, when it expires, and what is staged. An empty response means none is in progress.

From Go

The gitlab.com/rackn/provision/v4/api package wraps the sequence above. Prefer it over hand-rolling the transaction: CommitContentArchiveUpdate merges staged items to the highest version per name, drops adds that are also being removed, and handles the 503/Retry-After retry — all of which a direct REST caller has to reproduce.

  • CheckContentArchiveSupport — the feature gate
  • UploadContentArchive, DeleteContentArchive — one archive, whole transaction
  • StartContentArchiveUpdate, StageContentArchive, CommitContentArchiveUpdate, CancelContentArchiveUpdate — the primitives, for batching many archives into one commit
  • OpenContentArchive — parse a .drpca locally, no endpoint involved

See the generated reference for signatures.

References