Skip to content

feat(blaze): unify sandbox API routes under /v1/sandboxes #2535

Description

@WeissonHan

Problem

#2000 introduced /v1/sandboxes collection and item routes while retaining /v1/instances as compatibility aliases. The route families are still inconsistent: some operations are available under both names, while reset remains available only as POST /v1/instances/{id}/reset.

This forces clients to know operation-specific naming exceptions and leaves the canonical sandbox API incomplete.

Proposed behavior

Make /v1/sandboxes the canonical namespace for every sandbox operation.

  • Add a /v1/sandboxes equivalent for every supported /v1/instances route.
  • Route both names through the same handlers and preserve identical status codes, response bodies, idempotency, authorization, and side effects.
  • Keep /v1/instances as a documented compatibility alias during an explicit migration window.
  • Define the deprecation and eventual removal policy for /v1/instances before removing any route.

Acceptance criteria

  • Inventory every current /v1/instances route and its /v1/sandboxes equivalent.
  • Add missing sandbox-named routes, including POST /v1/sandboxes/{id}/reset.
  • Preserve the reset contract established by fix(blaze)!: reject incomplete reset and pool use #2290: malformed IDs return 400, unknown IDs return 404, invalid lifecycle states return 422, and a running sandbox returns 501 without state or ownership changes until complete reset is implemented.
  • Prove route equivalence through HTTP-level tests without duplicating business logic.
  • Use /v1/sandboxes in primary examples and client-facing documentation.
  • Mark /v1/instances as a compatibility namespace and document its migration window.
  • Add release notes before removing any compatibility route.

Scope

This issue does not implement successful reset behavior and does not authorize immediate removal of /v1/instances. It tracks namespace consistency and a compatible migration plan.

Related: #2000, #2290, #2472.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions