diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 9239d96..49d7760 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -1,62 +1,62 @@ .. _vault-primer: Getting started =============== The Vault is a service in charge of reconstructing parts of the archive as self-contained bundles, that can then be imported locally, for instance in a Git repository. This is basically where you can do a ``git clone`` of a repository stored in Software Heritage. The Vault is asynchronous : you first need to do a request to prepare the bundle you need, and then a second request to fetch the bundle once the Vault has finished to reconstitute the bundle. Example: retrieving a directory ------------------------------- First, ask the Vault to prepare your bundle: .. code:: shell - curl -X POST https://archive.softwareheritage.org/1/vault/directory/:dir_id/ + curl -X POST https://archive.softwareheritage.org/api/1/vault/directory/:dir_id/ where ``:dir_id`` is a :py:func:`directory identifier `. This initial request and all subsequent requests to this endpoint will return some JSON data containing information about the progress of bundle creation: .. code:: json { "id": 42, "fetch_url": "/api/1/vault/directory/:dir_id/raw/", "obj_id": ":dir_id", "obj_type": "directory", "progress_message": "Creating tarball...", "status": "pending" } Once the status is ``done``, you can fetch the bundle at the address given in the ``fetch_url`` field. .. code:: shell - curl -o bundle.tar.gz https://archive.softwareheritage.org/1/vault/directory/:dir_id/raw + curl -o bundle.tar.gz https://archive.softwareheritage.org/api/1/vault/directory/:dir_id/raw tar xaf bundle.tar.gz E-mail notifications -------------------- You can also ask to be notified by e-mail once the bundle you requested is ready, by giving an ``email`` POST parameter: .. code:: shell curl -X POST -d 'email=example@example.com' \ - https://archive.softwareheritage.org/1/vault/directory/:dir_id/ + https://archive.softwareheritage.org/api/1/vault/directory/:dir_id/ API reference ~~~~~~~~~~~~~ For a more exhaustive overview of the Vault API, see the :ref:`vault-api-ref`.