Publish API

Manages published repositories.

Publish APIs use following convention to identify published repositories: /api/publish/:prefix/:distribution. :distribution is distribution name, while :prefix is [<storage>:]<prefix> (storage is optional, it defaults to empty string), if publishing prefix contains slashes /, they should be replaced with underscores (_) and underscores should be replaced with double underscore (__). To specify root :prefix, use :., as . is ambigious in URLs.

Published repository properties:

NameTypeDescription
Storagestringstorage kind (empty for local filesystem, s3 for S3 and swift for Swift)
Prefixstringpublishing prefix, . for root
Distributionstringdistribution name
SourceKindstringtype of published repository: snapshot for snapshot, local for local repositories
Sources[]Sourcelist of sources, Component and Name of local repository/snapshot
Architectures[]stringlist of architectures published, e.g. ["i386", "amd64"]
Labelstringvalue of Label: field in published repository stanza
Originstringvalue of Origin: field in published repository stanza
NotAutomaticstringsetting to yes indicates to the package manager to not install or upgrade packages from the repository without user consent 🛈
ButAutomaticUpgradesstringsetting to yes excludes upgrades from the NotAutomic setting 🛈
AcquireByHashboolprovide index files by hash

Signing options (all are optional):

NameTypeDescription
Skipboolif true, don’t sign published repository
GpgKeystringgpg key name (local to aptly server/user)
Keyringstringgpg keyring filename (local to aptly server/user)
SecretKeyringstringgpg secret keyring filename (local to aptly server/user)
Passphrasestringgpg key passphrase (if using over http, would be transmitted in clear text!)
PassphraseFilestringgpg passphrase file (local to aptly server/user)

List

GET /api/publish

List published repositories.

Example:

$ curl http://localhost:8080/api/publish
[{"AcquireByHash":false,"Architectures":["i386"],"Distribution":"trusty","Label":"","Origin":"","Prefix":".","SourceKind":"snapshot","Sources":[{"Component":"main","Name":"snap1"}],"Storage":""},{"AcquireByHash":false,"Architectures":["i386","source"],"Distribution":"wheezy","Label":"","Origin":"","Prefix":"testing","SourceKind":"local","Sources":[{"Component":"main","Name":"local-repo"}],"Storage":""}]

Publish Snapshot/Local Repo

POST /api/publish/:prefix

Publish local repository or snapshot under specified prefix. Storage might be passed in prefix as well, e.g. s3:packages/. To supply empty prefix, just remove last part (POST /api/publish)

JSON body params:

NameTypeDescription
SourceKindstring, requiredsource kind: local for local repositories and snapshot for snapshots
Sources[]Source, requiredlist of Component/Name objects, Name is either local repository or snapshot name
Distributionstringdistribution name, if missing aptly would try to guess from sources
Labelstringvalue of Label: field in published repository stanza
Originstringvalue of Origin: field in published repository stanza
ForceOverwriteboolwhen publishing, overwrite files in pool/ directory without notice
Architectures[]stringoverride list of published architectures
SigningSigningOptionsgpg options (see above)
NotAutomaticstringsetting to yes indicates to the package manager to not install or upgrade packages from the repository without user consent 🛈
ButAutomaticUpgradesstringsetting to yes excludes upgrades from the NotAutomic setting 🛈
SkipCleanupbooldon’t remove unreferenced files in prefix/component
AcquireByHashboolprovide index files by hash

Notes on Sources field:

  • when publishing single component repository, Component may be omitted, it would be guessed from source or set to default value main
  • for multiple component published repository, Component would be guessed from source if not set

GPG signing would happen in aptly server, using local to server gpg binary, keyrings.

It’s not possible to configure publishing endpoints via API, they should be set in configuration and require aptly server restart.

HTTP errors:

CodeDescription
400prefix/distribution is already used by another published repository
404source snapshot/repo hasn’t been found

Example:

$ curl -X POST -H 'Content-Type: application/json' --data '{"SourceKind": "local", "Sources": [{"Name": "local-repo"}], "Architectures": ["i386", "amd64"], "Distribution": "wheezy"}' http://localhost:8080/api/publish/:.
{"AcquireByHash":false,"Architectures":["amd64","i386"],"Distribution":"wheezy","Label":"","Origin":"","Prefix":".","SourceKind":"local","Sources":[{"Component":"main","Name":"local-repo"}],"Storage":""}

$ curl -X POST -H 'Content-Type: application/json' --data '{"SourceKind": "local", "Sources": [{"Name": "0XktRe6qMFp4b8C", "Component": "contrib"}, {"Name": "EqmoTZiVx8MGN65", "Component": "non-free"}], "Architectures": ["i386", "amd64"], "Distribution": "wheezy"}' http://localhost:8080/api/publish/debian_testing/
{"AcquireByHash":false,"Architectures":["amd64","i386"],"Distribution":"wheezy","Label":"","Origin":"","Prefix":"debian/testing","SourceKind":"local","Sources":[{"Component":"contrib","Name":"0XktRe6qMFp4b8C"},{"Component":"non-free","Name":"EqmoTZiVx8MGN65"}],"Storage":""}

Update Published Local Repo/Switch Published Snapshot

PUT /api/publish/:prefix/:distribution

API action depends on published repository contents:

  • if local repository has been published, published repository would be updated to match local repository contents
  • if snapshots have been been published, it is possible to switch each component to new snapshot

JSON body params:

NameTypeDescription
Snapshots[]Sourceonly when updating published snapshots, list of objects Component/Name
ForceOverwriteboolwhen publishing, overwrite files in pool/ directory without notice
SigningSigningOptionsgpg options (see above)
AcquireByHashboolprovide index files by hash

Example:

$ curl -X PUT -H 'Content-Type: application/json' --data '{"Snapshots": [{"Component": "main", "Name": "8KNOnIC7q900L5v"}]}' http://localhost:8080/api/publish/:./wheezy
{"AcquireByHash":false,"Architectures":["amd64","i386"],"Distribution":"wheezy","Label":"","Origin":"","Prefix":".","SourceKind":"local","Sources":[{"Component":"main","Name":"2y21K6aKBE5UJBQ"}],"Storage":""}

Drop Published Repository

DELETE /api/publish/:prefix/:distribution

Delete published repository, clean up files in published directory.

Query params:

NameDescription
forceforce published repository removal even if component cleanup fails

Usually ?force=1 isn’t required, but if due to some corruption component cleanup fails, ?force=1 could be used to drop published repository. This might leave some published repository files left under public/ directory.

Example:

$ curl -X DELETE http://localhost:8080/api/publish//wheezy
{}