/concepts/migrating-from-vola-spp/
Migrating from vola-spp
vola-spp is the earlier Python service that this one replaces. If your application has never called it, you can skip this page.
This version is a new API with no wire compatibility, and it starts empty with no data migration. The model is the same, so most of the work is changing paths and the shapes of a few requests.
What changes
Section titled “What changes”A file still belongs to a tenant and an instance, and still has a slug, a folder path, a version chain, is_public and is_global_public, thumbnails that answer 202 while the worker renders, share links, stats and UDC list, describe and read.
These are different:
- Paths lose the
/api/v1prefix and the/id/segments:/vola/files/tickets/<uuid>/<fileId>. - Visibility and move are one
PATCHwith a JSON body. - Shares are created with a JSON body and followed at
/vola/s/<token>. - Errors are
{error: {code, message}}with stable snake_case codes. - The key goes in
Authorization: Bearer, andX-Api-Keystill works.
There are also new things: resumable uploads, live lists over WebSocket, OCR, encryption, keyrings and an audit trail.
Authentication
Section titled “Authentication”| vola-spp | Now | |
|---|---|---|
| Header | X-API-Key |
Authorization: Bearer. X-Api-Key is accepted too, and header names are case-insensitive, so an existing X-API-Key keeps working. WebSockets use the subprotocol bearer.<key> |
| Key format | vola_live_…, vola_test_…, vola_admin_… |
The same prefixes, with only the SHA-256 stored |
| The keys themselves | New keys. The key table starts empty, so issue them with vola create-key |
|
| Scopes | A JSON list on the key | files:read, files:write, folders:read, folders:write, shares:write, keys:write, keyrings:write, encryption:caller, admin |
| Admin key | X-Tenant-Slug selects the tenant |
The same |
| Acting user | X-User-Id |
The same header, now also the owner of a keyring |
| Another tenant’s file | 404 or 403 |
Always 404 |
| Errors | {detail: …} |
{error: {code, message, …}} |
Main routes
Section titled “Main routes”:type/:id is instance_type/instance_id. The full table has every route and its @vol-a/client method.
| vola-spp | Now |
|---|---|
POST /api/v1/files/{type}/id/{id} |
POST /vola/files/:type/:id |
PUT /api/v1/files/{type}/id/{id}/slug/{slug} |
PUT /vola/files/:type/:id/slug/:slug |
GET /api/v1/files/{type}/id/{id}/id/{file_id} |
GET /vola/files/:type/:id/:fileId |
GET …/id/{file_id}/info |
GET /vola/files/:type/:id/:fileId/info |
GET …/id/{file_id}/thumb/{size}?crop= |
GET /vola/files/:type/:id/:fileId/thumb/:size?crop= |
PATCH …/id/{file_id}/visibility |
PATCH /vola/files/:type/:id/:fileId with {is_public, is_global_public} |
PATCH …/id/{file_id}/move |
PATCH /vola/files/:type/:id/:fileId with {folder_path} |
DELETE …/id/{file_id}/purge |
DELETE /vola/files/:type/:id/:fileId/purge |
POST /api/v1/folders/{type}/id/{id}/path/{path} |
POST /vola/folders/:type/:id/*path |
POST /api/v1/share |
POST /vola/shares with a JSON body |
DELETE /api/v1/share/id/{id} |
DELETE /vola/shares/:id |
GET /share/token/{t} |
GET /vola/s/:token |
GET /public/file/{id} |
GET /vola/public/:fileId |
GET /api/v1/stats/tenant |
GET /vola/stats/tenant |
GET /api/v1/instance-types |
GET /vola/instance-types |
POST /api/v1/admin/transfer |
POST /vola/admin/transfer |
POST /udc/list |
POST /vola/udc/list |
GET /api/lookups |
GET /vola/lookups |
What stays exactly the same
Section titled “What stays exactly the same”- The 202 thumbnail rule. A consumer that got this right against vola-spp needs no change. See Uploads and processing.
- The sizes
64,128,256and512, the cropscover,fitandattention, and WebP. Range,206,416,HEAD,ETagand304on downloads, andinlinefor images, video, audio and PDF.instance_idis a UUID,instance_typeis a lowercase identifier, and a slug names one live file.- The UDC
filescollection and its rule of a top-levelinstance_typefilter or an empty list, withdownload_urlandthumb_urlon every row. is_publicandis_global_public.- Content-addressed storage, dedup, soft delete, and purge when nothing references the blob.
X-Tenant-Slugfor admin keys andX-User-Idfor attribution.
What is gone or different
Section titled “What is gone or different”/share/token/{t}/downloadbecomes?download=1, and the password goes inX-Share-Password.X-File-Hashon downloads is gone. TheETagcarries the hash of a plain file.- Share passwords are argon2id, not bcrypt.
- An upload answers the file info directly (
201), and lists answer{files, next_cursor}. POST /admin/transferno longer creates the destination tenant, so it must exist.dry_runis new.EXIFandAI_SUMMARYjobs, which existed only in vola-spp’s vocabulary, do not exist.
No data migration
Section titled “No data migration”This version starts with a new database, a new storage directory and new keys. There is no script that reads vola-spp’s tables or its aa/bb/cc/<sha>.<ext> tree. The old tree keeps the extension in the blob name, and vola-spp’s rows carry no encryption, OCR or version metadata the new schema wants.
vola-spp keeps running for the consumers that have not moved. A consumer moves by pointing its configuration at the new server. If it needs its old files there, it uploads them again through the new API, from its own source of truth.
Share tokens are not carried over. Links sent out under vola-spp stay valid against vola-spp for as long as it runs.
Checklist for a consumer
Section titled “Checklist for a consumer”- Keys. Create the tenants and new keys on the new server (
vola create-tenant,vola create-key,create-admin-key) with the scopes the project needs. A backend that acts for several tenants keeps using an admin key andX-Tenant-Slug. See the CLI reference. - Base URL and prefix.
https://files.example.com/volareplaces the old host plus/api/v1. Replace a vola client module with@vol-a/clientin TypeScript, or rewrite its route table in another language. The/udc/*calls move under the prefix. - Uploads. Drop
/id/from the path. The field names (file,folder_path,folder_id,parent_id) are unchanged andmetadatais new. The answer is the file info itself. Above a few MiB from a browser, switch tovola.uploads.resumable()orVolaUploadButton. - Downloads and
info. Drop/id/, and read the hash fromETaginstead ofX-File-Hash. - Thumbnails. The path changes. Keep the
202handling, or adoptfiles.thumb()orVolaThumb. Check that the project’s cache layer does not key a202body by hash. - Visibility and move. Two routes become one
PATCHwith{is_public},{is_global_public}or{folder_path}. - Shares.
POST /vola/shareswith a JSON body. The link isurlfrom the answer, so setVOLA_PUBLIC_URLon the server./share/token/…URLs in templates become/vola/s/<token>. For an encrypted file theurlhas a#fragmentthe recipient’s client must send asX-Share-Secret, whichVolaClient.openSharedoes. - UDC.
POST /vola/udc/list,describeandreadtake the same filter language. Rows gainkind,encryption,processing_statusandocr. A UI moves to@jsudc/reactand@vol-a/react’sVolaFileBrowser. - Stats, instance types, lookups. Only the paths change.
- Errors. Map
{error: {code}}instead of{detail}. Codes to branch on include423 vola_locked,409 vola_integrityand503 encryption_unavailableif the project adopts encryption. They are all in the API reference. - Transfer.
POST /vola/admin/transfertakes the same body. Create the destination tenant first, and trydry_run: true. - Smoke test. Upload, read
info, download withRange, fetch a thumbnail until200, run a UDC list, open a share link without a key, delete and purge. Run it with Docker shows the commands. - Decommission the vola-spp key for that project once the switch is done.
Worth adopting while you are there
Section titled “Worth adopting while you are there”encryption: "tenant"on uploads, which is one header and no other client change.- Keyrings for per-user private files, with
VolaPinGate. - OCR text through
…/info?ocr=fulland the UDCocrfilter. - The audit trail into memento.
- Live lists instead of polling.
v1.1.1released built 519e3dc