Skip to content

File API Migration Guide: Legacy Routes to the Workspace API

DATAMIMIC 4.0 replaces the historical file routes (/files, /files_uri, /lock, /unlock) with the Workspace API. The legacy routes still work as compatibility adapters, but they are deprecated and will be removed in a future release. This guide maps every legacy route to its Workspace API replacement.

If you are not using the legacy file routes, you do not need this guide β€” see the API overview instead.

Why migrate

  • Removal planned: the legacy routes are compatibility adapters only and will be removed in a future release (see the 4.0.0 release notes).
  • Safe concurrent writes: the Workspace API fences every update with an ETag and a lock generation, so two clients can no longer silently overwrite each other. Legacy routes use compatibility handling and do not provide the same explicit lock-generation contract.
  • One source of truth for project state: /workspace/tree returns the authoritative file list with ETags in one call, replacing separate /files_uri and per-file lookups.

Endpoint mapping

Legacy route Method Workspace API replacement Method
/projects/{id}/files_uri GET /projects/{id}/workspace/tree GET
/projects/{id}/files/{path} GET /projects/{id}/workspace/files/{path} GET
/projects/{id}/files/create-from-upload POST /projects/{id}/workspace/files/{path} (with If-None-Match: *) PUT
/projects/{id}/files/create-from-default POST /projects/{id}/workspace/files/{path} (with If-None-Match: *) PUT
/projects/{id}/files/{path} PUT /projects/{id}/workspace/files/{path} (with If-Match + lock generation) PUT
/projects/{id}/files/{path}/rename PUT /projects/{id}/workspace/entries/move (first-party only, not in /external_openapi.json) POST
/projects/{id}/files/{path} DELETE /projects/{id}/workspace/entries/{path} (first-party only, not in /external_openapi.json) DELETE
/projects/{id}/files/{path}/unlock POST /projects/{id}/workspace/locks/acquire POST
/projects/{id}/files/{path}/lock POST /projects/{id}/workspace/locks/release POST

Rename and delete have no direct customer-facing Workspace equivalent yet β€” they are first-party-only endpoints. If your CI/CD integration needs them, contact DATAMIMIC support.

The legacy route names are inverted from their actual behavior: /unlock acquires a lock and /lock releases one (kept for backward compatibility β€” renaming them would be a breaking change). Map by behavior, not by name.

What actually changes

The legacy routes accept a bearer token and a file path; the Workspace API adds explicit concurrency headers so a write can't silently clobber another client's change:

  • X-DATAMIMIC-Client-Binding identifies your CI job or client process.
  • If-Match / ETag identifies the file version you read.
  • X-DATAMIMIC-Lock-Generation proves you hold the current lock, required for updating an existing file.
  • If-None-Match: * marks a create-only write β€” it fails instead of overwriting if the path already exists.

For the full request/response flow, headers, and worked curl examples, see the Workspace API guide β€” this guide only maps old routes to new ones.

Historical: API v1 (removed in 2.6.0)

An earlier /api/v1 surface existed before API v2. It was deprecated and then fully removed in release 2.6.0 β€” there is no /api/v1 in any current DATAMIMIC deployment, and this guide no longer documents its routes. If you are integrating against a pre-2.6.0 deployment, see that release's breaking changes and upgrade to API v2 first.

Support

If you run into issues migrating off the legacy file routes:

  1. Check the Workspace API guide for the full request flow and concurrency contract.
  2. Use the Swagger documentation to inspect the exact request and response schema for each endpoint.
  3. Contact the DATAMIMIC support team.