Page MenuHomeSoftware Heritage
Files F9342687

apidoc-header.html
No OneTemporary
Actions

apidoc-header.html
View Options

<nav class="bread-crumbs">
<ul><li>API</li></ul>
</nav>
<p>Welcome to Software Heritage project's API documentation.</p>
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
<p><strong>Table of Contents</strong></p>
<ul>
{% include 'includes/apidoc-header-toc.html' %}
</ul>
<!-- markdown-toc end -->
<h3 id="version">Version</h3>
<p>Current version is <a href="/api/1/">1</a>.</p>
<h3 id="schema">Schema</h3>
<p>Api access is over https and accessed through <a href="/api/1/">https://archive.softwareheritage.org/api/1/</a>.</p>
<p>Data is sent and received in json by default.</p>
<p>Examples:</p>
<ul>
<li><p><a href="/api/1/stat/counters/" class="uri">/api/1/stat/counters/</a></p></li>
<li><p>From the command line:</p>
<pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/stat/counters/</code></pre></li>
</ul>
<h4 id="mimetype-override">Mimetype override</h4>
<p>The response output can be sent as yaml provided the client specifies it using the header field.</p>
<p>Examples:</p>
<ul>
<li><p>From your favorite REST client API, execute the same request as before with the request header 'Accept' set to the 'application/yaml'.</p></li>
<li><p>From the command line:</p>
<pre class="shell"><code>curl -i -H &#39;Accept: application/yaml&#39; https://archive.softwareheritage.org/api/1/stat/counters/</code></pre></li>
</ul>
<h3 id="parameters">Parameters</h3>
<p>Some API endpoints can be used with local parameters. The url then needs to be adapted accordingly.</p>
<p>For example:</p>
<pre class="text"><code>https://archive.softwareheritage.org/api/1/&lt;endpoint-name&gt;?&lt;field0&gt;=&lt;value0&gt;&amp;&lt;field1&gt;=&lt;value1&gt;</code></pre>
<p>where:</p>
<ul>
<li>field0 is an appropriate field for the <endpoint-name> and value0</li>
<li>field1 is an appropriate field for the <endpoint-name> and value1</li>
</ul>
<h4 id="global-parameter">Global parameter</h4>
<p>One parameter is defined for all api endpoints <code>fields</code>. It permits to filter the output fields per key.</p>
<p>For example, to only list the number of contents, revisions, directories on the statistical endpoints, one uses:</p>
<p>Examples:</p>
<ul>
<li><p><a href="/api/1/stat/counters/?fields=content,directory,revision" class="uri">/api/1/stat/counters/?fields=content,directory,revision</a></p></li>
<li><p>From the command line:</p>
<pre class="shell"><code>curl https://archive.softwareheritage.org/api/1/stat/counters/\?fields\=content,directory,revision</code></pre></li>
</ul>
<p>Note: If the keys provided to filter on do not exist, they are ignored.</p>
<h3 id="client-errors">Client errors</h3>
<p>There are 2 kinds of error.</p>
<p>In that case, the http error code will reflect. Furthermore, the response is a dictionary with one key 'error' detailing the problem.</p>
<h4 id="bad-request">Bad request</h4>
<p>This means that the input is incorrect.</p>
<p>Example:</p>
<ul>
<li><p><a href="/api/1/content/1/" class="uri">/api/1/content/1/</a></p></li>
<li><p>From the command line:</p>
<pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/content/1/</code></pre></li>
</ul>
<p>The api content expects an hash identifier so the error will mention that an hash identifier is expected.</p>
<h4 id="not-found">Not found</h4>
<p>This means that the request is ok but we do not found the information the user requests.</p>
<p>Examples:</p>
<ul>
<li><p><a href="/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/" class="uri">/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/</a></p></li>
<li><p>From the command line:</p>
<pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/</code></pre></li>
</ul>
<p>The hash identifier is ok but nothing is found for that identifier.</p>
<h3 id="terminology">Terminology</h3>
<p>You will find below the terminology the project SWH uses. More details can be found on <a href="https://wiki.softwareheritage.org/index.php?title=Glossary">swh's wiki glossary page</a>.</p>
<h4 id="content">Content</h4>
<p>A (specific version of a) file stored in the archive, identified by its cryptographic hashes (SHA1, &quot;git-like&quot; SHA1, SHA256) and its size.</p>
<p>Also known as: Blob Note.</p>
<h4 id="cryptographic-hash">(Cryptographic) hash</h4>
<p>A fixed-size &quot;summary&quot; of a stream of bytes that is easy to compute, and hard to reverse.</p>
<p>Also known as: Checksum, Digest.</p>
<h4 id="directory">Directory</h4>
<p>A set of named pointers to contents (file entries), directories (directory entries) and revisions (revision entries).</p>
<h4 id="origin">Origin</h4>
<p>A location from which a coherent set of sources has been obtained.</p>
<p>Also known as: Data source.</p>
<p>Examples:</p>
<ul>
<li>a Git repository</li>
<li>a directory containing tarballs</li>
<li>the history of a Debian package on snapshot.debian.org.</li>
</ul>
<h4 id="project">Project</h4>
<p>An organized effort to develop a software product.</p>
<p>Projects might be nested following organizational structures (sub-project, sub-sub-project), are associated to a number of human-meaningful metadata, and release software products via Origins.</p>
<h4 id="release">Release</h4>
<p>A revision that has been marked by a project as noteworthy with a specific, usually mnemonic, name (for instance, a version number).</p>
<p>Also known as: Tag (Git-specific terminology).</p>
<p>Examples:</p>
<ul>
<li>a Git tag with its name</li>
<li>a tarball with its name</li>
<li>a Debian source package with its version number.</li>
</ul>
<h4 id="revision">Revision</h4>
<p>A &quot;point in time&quot; snapshot in the development history of a project.</p>
<p>Also known as: Commit</p>
<p>Examples:</p>
<ul>
<li>a Git commit</li>
</ul>
<h3 id="opened-endpoints">Opened endpoints</h3>
<p>Accessible through <a href="/api/1/">https://archive.softwareheritage.org/api/1/</a>.</p>

File Metadata

Mime Type
text/html
Expires
Fri, Jul 4, 12:56 PM (1 w, 3 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3296281

Event Timeline

About · Developer information · Legal