Repository navigation
Description
Is your feature request related to a problem?
The v1 API can create a version but can never change or remove one afterwards. For an "external URL" version (files[].externalUrl) that means a wrong URL — a typo, or the file host renaming its assets — can only be repaired by deleting the version in the web UI and re-creating it through the API.
$ curl -X OPTIONS -i https://hangar.papermc.io/api/v1/projects/{slug}/versions/{name}
allow: GET,HEAD,OPTIONS # no PATCH, no DELETE
$ curl -X PATCH .../versions/{name} -> 405
$ curl -X DELETE .../versions/{name} -> 405
/v3/api-docs only exposes GET, POST /upload (create) and /stats for version paths. Editing and deleting exist only under /api/internal/versions/version/{projectId}/{versionId}/... (including a soft delete and a hardDelete), which can't be driven by an API key.
Real-world case: I maintain FakePlayer-CE, a Paper plugin. A batch of versions was published pointing at
.../releases/download/fp.build16/fakeplayer-fp.fp.build16.jar -> 404
.../releases/download/fp.build16/fakeplayer-fp.build16.jar -> 200
Every download link on the project page 404'd. Nothing surfaced it: external downloads aren't tracked (stats stay at 0, which reads as "nobody uses this"), and GET /versions/{name}/PAPER/download is a 404 for external files too (see #1122), so a scripted check against the API also reports "fine".
The only repair was to delete and re-create 14 versions. Both halves had to be done by hand: deletion because there is no DELETE, re-creation 14 times because the upload endpoint creates one version per call. And re-creating has a side effect users see — versions are listed by creation time (by design, see #1196), so the re-created old versions landed above the genuinely recent ones, and the download button follows the most recently created version. After an otherwise harmless metadata fix the public list read:
build9, build8, build7, ... build3, build16, build14, ...
Describe the solution you'd like
Four things, in order of how much they would have helped:
-
PATCH /api/v1/projects/{slug}/versions/{name}— accept at leastfiles[].externalUrl, ideally alsodescription,platformDependenciesandpluginDependencies. Even external-URL-only would remove the delete/re-create cycle entirely. -
DELETE /api/v1/projects/{slug}/versions/{name}— parity with what the web UI already lets a project member do, so bulk cleanup is scriptable. Reusing the existing soft-delete semantics (restorable, like the internaldeleterather thanhardDelete) would be enough; no new capability, just no longer requiring a browser. Right now removing 14 bad versions meant 14 clicks. -
Validate the external URL on create (and on edit) —
HEADit, reject or warn on non-2xx. Hangar would then have refused fourteen dead links instead of silently publishing them, and none of the above would have been necessary. -
Document that
GET /api/v1/projects/{slug}/versions?limit=NcapsNat 25 and silently clamps larger values (the response'spagination.limitsays 25). My first query usedlimit=100and returned 5 entries, which looked like "all the versions there are".
Describe alternatives you've considered
- Delete + re-create through the web UI. What I ended up doing. Loses
createdAtordering and download stats, and isn't scriptable at either end. - Add a second file named like the typo. I uploaded duplicate assets so the broken URLs would resolve. Works, but doubles storage per release, only helps when you control the file host, and then has to be cleaned up again later.
- Talking to
/api/internal/.... Not usable with an API key, and I'd rather not have CI depend on an internal route. - Reordering / pinning. Deliberately not asking for it — I read Ability to sort versions and selection for the main download-button #1196 and kennytv's reasoning about non-chronological creation. The point is not needing a re-create in the first place.
Other
Happy to write the PATCH / DELETE handlers if you can point at where version mutations belong (whether v1 should reuse the internal save/delete logic or get proper routes). Reproducing both 405s is one curl each against any project with an existing version.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNew
Activity
[-]API: let a published version be edited (at least files[].externalUrl) instead of forcing delete + re-create[/-][+]API: allow editing and deleting a published version (at least files[].externalUrl)[/+]