Summary
The 1.9.1 OpenAPI document (455 operations) contains almost no enum constraints and several described vocabularies differ from what the server accepts. The live 1.9.1 backend serves this spec at /api/v1/openapi.json.
Discrepancies found by probing:
repo_type: accepted local / remote / virtual; hosted (used in docs and the description) is rejected.POST /api/v1/auth/tokens requires scopes (array); the allowed values (read:artifacts, write:artifacts, delete:artifacts, promote:artifacts, read:repositories, write:repositories, delete:repositories, read:users, write:users, trigger:sync, admin, *) are only discoverable from the 422 error text.storage_backend, format, principal_type, target_type, actions[], curation_default_action have no enum although curation_default_action's description claims "the allowed set is spelled out in the schema".- Migration connections:
auth_type accepts basic_auth / api_token, the description says basic / token.
PATCH /api/v1/repositories/{key} requires curation_default_action even for unrelated updates.- POST responses use 200 / 201 / 202 inconsistently; DELETE uses 200 / 204.
Two of these are API behaviour, not only documentation gaps: curation_default_action being required on PATCH /api/v1/repositories/{key} and scopes being required on token creation both need a fix in the handlers, not just an annotation change.
Impact
Any client generated from the spec is wrong at request time; we logged 18 such discrepancies while writing a Terraform provider and a load generator.
Suggested fix
Add enum to the fields above, fix the vocabularies in descriptions, and make curation_default_action optional on PATCH.
Environment
- Artifact Keeper backend
1.9.1, web 1.9.0, Helm chart artifact-keeper 1.9.9 (artifact-keeper/artifact-keeper-iac)
- Kubernetes 1.34 (AKS, westeurope), Envoy Gateway in front, in-cluster Postgres from the chart
- Storage:
STORAGE_BACKEND=filesystem default (per-pod ephemeral PVC), repositories pinned to azure (Blob, Shared Key) and s3 (eu-central-1)
- 1 to 3 backend replicas (HPA) depending on the test
Note: This issue, alongside others created by me today, has been discovered during the stress-testing and evaluation of ArtifactKeeper in a prod-like environment on an AKS cluster with both S3 and Azure Blob Storage as backends. The test was designed to specifically discover edge cases, with multiple terrabytes of data going through the deployment. Thank you for the hard work and please let me know if contributions on these issues are wanted.
Summary
The 1.9.1 OpenAPI document (455 operations) contains almost no
enumconstraints and several described vocabularies differ from what the server accepts. The live 1.9.1 backend serves this spec at/api/v1/openapi.json.Discrepancies found by probing:
repo_type: acceptedlocal/remote/virtual;hosted(used in docs and the description) is rejected.POST /api/v1/auth/tokensrequiresscopes(array); the allowed values (read:artifacts,write:artifacts,delete:artifacts,promote:artifacts,read:repositories,write:repositories,delete:repositories,read:users,write:users,trigger:sync,admin,*) are only discoverable from the 422 error text.storage_backend,format,principal_type,target_type,actions[],curation_default_actionhave no enum althoughcuration_default_action's description claims "the allowed set is spelled out in the schema".auth_typeacceptsbasic_auth/api_token, the description saysbasic/token.PATCH /api/v1/repositories/{key}requirescuration_default_actioneven for unrelated updates.Two of these are API behaviour, not only documentation gaps:
curation_default_actionbeing required onPATCH /api/v1/repositories/{key}andscopesbeing required on token creation both need a fix in the handlers, not just an annotation change.Impact
Any client generated from the spec is wrong at request time; we logged 18 such discrepancies while writing a Terraform provider and a load generator.
Suggested fix
Add
enumto the fields above, fix the vocabularies in descriptions, and makecuration_default_actionoptional on PATCH.Environment
1.9.1, web1.9.0, Helm chartartifact-keeper1.9.9 (artifact-keeper/artifact-keeper-iac)STORAGE_BACKEND=filesystemdefault (per-pod ephemeral PVC), repositories pinned toazure(Blob, Shared Key) ands3(eu-central-1)Note: This issue, alongside others created by me today, has been discovered during the stress-testing and evaluation of ArtifactKeeper in a prod-like environment on an AKS cluster with both S3 and Azure Blob Storage as backends. The test was designed to specifically discover edge cases, with multiple terrabytes of data going through the deployment. Thank you for the hard work and please let me know if contributions on these issues are wanted.