Vault#

GET /api/1/vault/flat/(swhid)/#

POST /api/1/vault/flat/(swhid)/#

Request the cooking of a simple archive, typically for a directory.

That endpoint enables to create a vault cooking task for a directory through a POST request or check the status of a previously created one through a GET request.

Once the cooking task has been executed, the resulting archive can be downloaded using the dedicated endpoint GET /api/1/vault/flat/(swhid)/raw/:

$ curl -LOJ https://archive.softwareheritage.org/api/1/vault/flat/swh:1:dir:*/raw/

Then to extract the cooked directory in the current one, use:

$ tar xvf path/to/swh_1_*.tar.gz

(replace swh:1:dir:* with the SWHID of the requested directory).

Parameters:

swhid (string) – the object’s SWHID

Query Parameters:

email (string) – e-mail to notify when the archive is ready

Request Headers:

Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers:

Content-Type – this depends on Accept header of request

Response JSON Object:

fetch_url (string) – the url from which to download the archive once it has been cooked (see GET /api/1/vault/flat/(swhid)/raw/)
progress_message (string) – message describing the cooking task progress
id (number) – the cooking task id
status (string) – the cooking task status (either new, pending, done or failed)
swhid (string) – the identifier of the object to cook

Status Codes:

200 OK – no error
400 Bad Request – an invalid directory identifier has been provided
404 Not Found – requested directory did not receive any cooking request yet (in case of GET) or cannot be found in the archive (in case of POST)

GET /api/1/vault/flat/(swhid)/raw/#

Fetch the cooked archive for a flat bundle.

See GET /api/1/vault/flat/(swhid)/ to get more details on ‘flat’ bundle cooking.

Parameters:

swhid (string) – the SWHID of the object to cook

Response Headers:

Content-Type – application/gzip

Status Codes:

200 OK – no error
404 Not Found – requested directory did not receive any cooking request yet (in case of GET) or cannot be found in the archive (in case of POST)

GET /api/1/vault/git-bare/(swhid)/#

POST /api/1/vault/git-bare/(swhid)/#

Request the cooking of a git-bare archive or check its cooking status.

That endpoint enables to create a git-bare archive cooking task for a:

revision: produced repository only includes a single branch heading to the revision
release: produced repository only includes a single branch heading to the release
snapshot: produced repository includes all branches and releases contained in the snapshot
directory: produced repository only includes a single branch with a single commit targeting the directory

A cooking task must be created through a POST request while checking the status of a previously created one can be done through a GET request.

Once the cooking task has been executed, the resulting git-bare archive can be downloaded using the dedicated endpoint GET /api/1/vault/git-bare/(swhid)/raw/:

$ curl -LOJ https://archive.softwareheritage.org/api/1/vault/git-bare/swh:1:*/raw/

Then to import the repository in the current directory, use:

$ tar -xf path/to/swh_1_*.git.tar
$ git clone swh:1:*.git new_repository

(replace swh:1:* with the SWHID of the requested revision or snapshot).

This will create a directory called new_repository, which is a git repository containing the requested objects.

Parameters:

swhid (string) – the revision’s or snapshot’s permanent identifier

Query Parameters:

email (string) – e-mail to notify when the git-bare archive is ready

Request Headers:

Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers:

Content-Type – this depends on Accept header of request

Response JSON Object:

fetch_url (string) – the url from which to download the archive once it has been cooked (see GET /api/1/vault/git-bare/(swhid)/raw/)
progress_message (string) – message describing the cooking task progress
id (number) – the cooking task id
status (string) – the cooking task status (new/pending/done/failed)
swhid (string) – the identifier of the object to cook

Status Codes:

200 OK – no error
404 Not Found – requested directory did not receive any cooking request yet (in case of GET) or cannot be found in the archive (in case of POST)

GET /api/1/vault/git-bare/(swhid)/raw/#

Fetch the cooked git-bare archive for a revision.

See GET /api/1/vault/git-bare/(swhid)/ to get more details on git-bare cooking.

Parameters:

swhid (string) – the revision’s permanent identifier

Response Headers:

Content-Type – application/x-tar

Status Codes:

200 OK – no error
404 Not Found – requested directory did not receive any cooking request yet (in case of GET) or cannot be found in the archive (in case of POST)

GET /api/1/vault/gitfast/(swhid)/#

POST /api/1/vault/gitfast/(swhid)/#

Request the cooking of a gitfast archive for a revision or check its cooking status.

That endpoint enables to create a vault cooking task for a revision through a POST request or check the status of a previously created one through a GET request.

Once the cooking task has been executed, the resulting gitfast archive can be downloaded using the dedicated endpoint GET /api/1/vault/gitfast/(swhid)/raw/:

$ curl -LOJ https://archive.softwareheritage.org/api/1/vault/gitfast/swh:1:rev:*/raw/

Then to import the revision in the current directory, use:

$ git init
$ zcat path/to/swh_1_rev_*.gitfast.gz | git fast-import
$ git checkout HEAD

(replace swh:1:rev:* with the SWHID of the requested revision).

Parameters:

swhid (string) – the revision’s permanent identifiers

Query Parameters:

email (string) – e-mail to notify when the gitfast archive is ready

Request Headers:

Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers:

Content-Type – this depends on Accept header of request

Response JSON Object:

fetch_url (string) – the url from which to download the archive once it has been cooked (see GET /api/1/vault/gitfast/(swhid)/raw/)
progress_message (string) – message describing the cooking task progress
id (number) – the cooking task id
status (string) – the cooking task status (new/pending/done/failed)
swhid (string) – the identifier of the object to cook

Status Codes:

200 OK – no error
404 Not Found – requested directory did not receive any cooking request yet (in case of GET) or cannot be found in the archive (in case of POST)

GET /api/1/vault/gitfast/(swhid)/raw/#

Fetch the cooked gitfast archive for a revision.

See GET /api/1/vault/gitfast/(swhid)/ to get more details on gitfast cooking.

Parameters:

rev_id (string) – the revision’s sha1 identifier

Response Headers:

Content-Type – application/gzip

Status Codes:

200 OK – no error
404 Not Found – requested directory did not receive any cooking request yet (in case of GET) or cannot be found in the archive (in case of POST)

GET /api/1/vault/directory/(dir_id)/#: This endpoint was replaced by GET /api/1/vault/flat/(swhid)/

GET /api/1/vault/directory/(dir_id)/raw/#: This endpoint was replaced by GET /api/1/vault/flat/(swhid)/raw/

GET /api/1/vault/revision/(rev_id)/gitfast/#: This endpoint was replaced by GET /api/1/vault/gitfast/(swhid)/