swh.web.vault.api_views module#

swh.web.vault.api_views.api_vault_cook_flat(request: Request, swhid: str)[source]#
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:
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)

swh.web.vault.api_views.api_vault_cook_directory(request: Request, dir_id: str)[source]#
GET /api/1/vault/directory/(dir_id)/#

This endpoint was replaced by GET /api/1/vault/flat/(swhid)/

swh.web.vault.api_views.api_vault_download_flat(request: Request, swhid: str)[source]#
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:
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)

swh.web.vault.api_views.api_vault_download_directory(request: Request, dir_id: str)[source]#
GET /api/1/vault/directory/(dir_id)/raw/#

This endpoint was replaced by GET /api/1/vault/flat/(swhid)/raw/

swh.web.vault.api_views.api_vault_cook_gitfast(request: Request, swhid: str)[source]#
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:
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)

swh.web.vault.api_views.api_vault_cook_revision_gitfast(request: Request, rev_id: str)[source]#
GET /api/1/vault/revision/(rev_id)/gitfast/#

This endpoint was replaced by GET /api/1/vault/gitfast/(swhid)/

swh.web.vault.api_views.api_vault_download_revision_gitfast(request: Request, swhid: str)[source]#
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:
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)

swh.web.vault.api_views.api_vault_cook_git_bare(request: Request, swhid: str)[source]#
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:
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)

swh.web.vault.api_views.api_vault_download_revision_git_bare(request: Request, swhid: str)[source]#
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:
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)