Versioning & deprecation

Type: Reference · Audience: Anyone building a long-lived integration

Two kinds of versioning

Molecule Studio uses two independent version systems:

1. API versions identify a compatible HTTP contract in the URL, such as /api/v1.
2. Scientific resource revisions identify immutable states of a durable scientific resource, such as version 7 of a molecular project.

An API version can serve many resource revisions. Changing a project from revision 7 to 8 does not change the API version.

URL API versioning

The current public API version is v1:

/api/v1

The machine-readable OpenAPI 3.1 contract is available from:

• /api/v1/openapi.json — canonical document
• /.well-known/openapi.json — discovery alias

The OpenAPI document covers the customer-facing /api/v1 operations explicitly listed in that document. Its component schemas are generated from runtime validation schemas, and CI checks documented operations against the implemented /api/v1 route boundary.

Molecular project operations are part of the generated public contract under /api/v1/molecular/projects. The older authenticated application routes under /api/molecular/projects are deprecated compatibility routes. Their documented successor is the corresponding /api/v1/molecular/projects operation; new integrations must use only the v1 contract.

Scientific resource identity and revisions

A molecular project receives a permanent Molecule UUID when it is created. That UUID remains the public identity of the project across all revisions and must not be replaced by a storage-provider or repository identifier.

Each explicit save appends an immutable, monotonically increasing revision. Responses expose currentVersion, which identifies the current editable head. Historical revisions retain their version number, content SHA-256, creation time, and restore provenance when applicable.

Autosave or transient browser state is not a governed revision. Restoring an old revision never rewrites history: it copies that content into a new successor revision and records the source version.

Optimistic concurrency

Mutation clients must read the current version and send it back as expectedVersion on every save, delete, save-and-share, share revocation, or restore request. The public v1 contract rejects a missing, non-integer, or non-positive expectedVersion.

If expectedVersion does not equal the current head, the mutation fails without overwriting newer work:

{
  "error": "Project version conflict",
  "code": "VERSION_CONFLICT",
  "currentVersion": 8
}

The response status is 409 Conflict. Clients must preserve local edits and ask the user to reload, inspect history, or deliberately resolve the conflict. They must not automatically retry a stale mutation with the returned version.

Molecular Projects v1 endpoints

Operation	Endpoint	Scope	Preconditions
List projects	GET /api/v1/molecular/projects	projects:read	Optional limit and opaque cursor
Create project	POST /api/v1/molecular/projects	projects:write	Required Idempotency-Key
Read project	GET /api/v1/molecular/projects/{projectId}	projects:read
Save successor	PUT /api/v1/molecular/projects/{projectId}	projects:write	Required Idempotency-Key and expectedVersion
Delete project	DELETE /api/v1/molecular/projects/{projectId}	projects:write	Required expectedVersion
List revisions	GET /api/v1/molecular/projects/{projectId}/revisions	projects:read	Optional limit and opaque cursor
Read revision	GET /api/v1/molecular/projects/{projectId}/revisions/{version}	projects:read
Restore revision	POST /api/v1/molecular/projects/{projectId}/revisions/{version}/restore	projects:write	Required Idempotency-Key and expectedVersion
Save and share	POST /api/v1/molecular/projects/{projectId}/shares	projects:write	Required Idempotency-Key and expectedVersion
Revoke share	DELETE /api/v1/molecular/projects/{projectId}/shares	projects:write	Required expectedVersion

List operations return an opaque nextCursor; clients must pass it back unchanged and must not construct or inspect cursor values. Idempotent mutation replays include Idempotency-Replayed: true. Project creation returns Location, and rate-limit failures expose the documented rate-limit and retry headers.

Historical deep links

An owned historical project revision has a stable deep link:

/molecular/studio?project={projectId}&revision={version}

Historical inspection is read-only. The Studio disables title editing, save, and share while a historical revision is open. A user must restore the revision, producing a new current version, before editing it as project head.

Revision-pinned shares

Public project shares are capabilities pinned to the immutable revision selected when the token is created or rotated. The share path is:

/molecular/shared/{token}

Later private saves do not move an existing share to a newer revision. Revocation invalidates the capability. Mutable “latest version” sharing is not part of this contract.

Canonical links for docking resources

Durable docking responses expose a relative uiLinks.studio value that opens the authorization-checked resource in Molecular Studio:

Resource	Canonical link
Docking batch	/molecular/studio?dockingBatch={batchId}
Docking run	/molecular/studio?dockingRun={runId}
Docking result	/molecular/studio?dockingResult={resultId}
Docking pose	/molecular/studio?dockingPose={poseId}

REST clients, agents, and MCP tools should return the canonical link supplied by the API rather than constructing a different route. Canonical UI links are durable presentation metadata, not signed artifact URLs, and do not bypass authorization.

What counts as an API breaking change

Within v1 we will not, without a new major API version:

• remove a documented endpoint, field, or enum value
• add a new required request field to a documented operation
• change a field's type or existing meaning
• tighten validation so a previously valid documented request fails

We may make additive changes within v1:

• add endpoints or optional request fields
• add response fields
• add error code values
• add values to response-only enums

Clients should ignore unknown response fields and handle unknown error codes generically.

Deprecation policy

When a documented endpoint or field is scheduled for removal in a future major API version:

1. It is marked deprecated: true in OpenAPI.
2. Deprecated endpoint responses include a Deprecation header and, when a replacement exists, a Link header with rel="successor-version".
3. A minimum 90-day migration window is provided before removal.

Recommended client practices

• Pin generated clients to /api/v1 and only rely on operations present in OpenAPI.
• Treat project UUIDs as permanent identities and revision numbers as immutable resource states.
• Persist currentVersion and send expectedVersion with every project mutation.
• Handle 409 VERSION_CONFLICT as a user-visible concurrency decision, not a retry signal.
• Preserve revision and uiLinks values returned by the service.
• Never persist short-lived signed artifact URLs as canonical links.
• Read rate-limit and deprecation headers rather than hard-coding policy values.

---

See also

• Errors & rate limits
• Getting started