Uploads: replace a file in place, and say which file each version is - #433
Uploads: replace a file in place, and say which file each version is#433jeremy wants to merge 1 commit into
Conversation
cdea8ec to
38479ac
Compare
|
Updated: both create endpoints now document the Synced from bc3 |
38479ac to
5d6cda9
Compare
|
Updated: documents that the Synced from bc3 |
5d6cda9 to
f7be88e
Compare
|
Re-synced onto current master and re-pinned to the source repo's master. The earlier revision of this branch predated a follow-up that settled the endpoint's input contract, so it would have published docs that omit behavior already live: Synced from bc3 |
Documents a new endpoint for replacing an upload's file, and corrects the
existing versions documentation.
New: Create an upload version
POST /uploads/2/versions.jsonreplaces the file of an existing upload. Theupload keeps its ID, its URL and its comments, and the previous file stays
available as a past version.
Until now the only way to publish a new file was
POST /vaults/2/uploads.json,which creates a new upload with a new ID and a new URL. If you're shipping
successive releases of the same artifact, that means a folder filling up with
app-v0.8.1.exe,app-v0.8.2.exe, … and a download link that has to changeevery time. Use the new endpoint when you want the link to keep working.
Takes the same
attachable_sgidas Create anattachment, plus optional
base_name,description,notifyandsubscriptions. Returns201 Createdwith the upload's JSON representation.
descriptionis presence-aware: omit it to carry the previous version'sdescription forward, or send
""ornullto clear it.notifyandsubscriptionscontrol who hears about the replacement, the sameway they do elsewhere in the API:
defaultnotifies people subscribed toproject notifications,
everyonenotifies the whole project, andcustomnotifies the people named in
subscriptions. Omit both to notify nobody.Notified people are subscribed to the upload. Client visibility isn't a
parameter here — a replacement never changes who can see an upload, so clients
are in the audience only when the upload is already visible to them.
The project-scoped
POST /buckets/1/uploads/2/versions.jsonalso works and islisted under the legacy routes.
Corrected: Get upload versions
The previous text said "Each version event represents a file replacement."
That was wrong — as the example response directly beneath it showed, with
"action": "created".Three actions appear:
createdandactivemark the upload's publication, andblob_changedmarks a file replacement. Filter onblob_changedto list onlyreplacements.
New: the
uploadobject on version eventsVersion events previously carried event metadata only, so you could tell that
something changed but not which file. Each version event now includes an
uploadobject:filename,content_typeandbyte_size— the file as it was at thatversion.
download_url— that specific version's file. The upload's owndownload_urlalways serves the latest.
app_download_url— the equivalent link for the Basecamp web app.current—truefor the most recent version,falsefor the rest.One nuance worth reading before you rely on
current: it means the newestversion, which isn't necessarily the file you get from the upload's own
download_url. Updating an upload changes its metadata without recording a newversion, so the two can differ. The documentation says this explicitly.
Also: Update an upload's parameters
Update an upload never listed what it
accepts. It takes
base_nameanddescription, and it changes metadata only —the file itself is replaced through the new versions endpoint. Sending
""forbase_namekeeps the current name; sending""ornullfordescriptionclears it.
This is an additive change. Existing fields are unchanged.
Synced from bc3
doc/api/byscript/api/sync_to_bc3_api— not a hand-edit.