Copyright (C) 2015-2018 The Software Heritage developers
See the AUTHORS file at the top-level directory of this distribution
License: GNU Affero General Public License version 3, or any later version
See top-level LICENSE file for more information
{% endcomment %}
<ulclass="list-inline">
<liclass="list-inline-item">
<ahref="#endpoint-index">Endpoint index</a>
</li>
<liclass="list-inline-item">
<ahref="#data-model">Data model</a>
</li>
<liclass="list-inline-item">
<ahref="#version">Version</a>
</li>
<liclass="list-inline-item">
<ahref="#schema">Schema</a>
</li>
<liclass="list-inline-item">
<ahref="#parameters">Parameters</a>
</li>
<liclass="list-inline-item">
<ahref="#errors">Errors</a>
</li>
<liclass="list-inline-item">
<ahref="#pagination">Pagination</a>
</li>
<liclass="list-inline-item">
<ahref="#rate-limiting">Rate limiting</a>
</li>
</ul>
<h4id="endpoint-index">Endpoint index</h4>
<p>You can jump directly to the
<strong>
<ahref="/api/1/">endpoint index</a>
</strong>, which lists all available API functionalities, or read on for more general information about the API.</p>
<h4id="data-model">Data model</h4>
<p>The
<ahref="https://www.softwareheritage.org/">Software Heritage</a> project harvests publicly available source code by tracking software distribution channels such as
version control systems, tarball releases, and distribution packages.</p>
<p>All retrieved source code and related metadata are stored in the Software Heritage archive, that is conceptually a
<ahref="https://en.wikipedia.org/wiki/Merkle_tree">Merkle DAG</a>. All nodes in the graph are content-addressable, i.e., their node identifiers are computed by hashing their
content and, transitively, that of all nodes reachable from them; and no node or edge is ever removed from the graph: the
Software Heritage archive is an append-only data structure.</p>
<p>The following types of objects (i.e., graph nodes) can be found in the Software Heritage archive
<p>While API endpoints will return different kinds of errors depending on their own semantics, some error patterns are common
across all endpoints.</p>
<p>Sending malformed data, including syntactically incorrect object identifiers, will result in a
<code>400 Bad Request</code> HTTP response. Example:</p>
<ul>
<li>
<ahref="/api/1/content/deadbeef/"class="uri">/api/1/content/deadbeef/</a> (client error: "deadbeef" is too short to be a syntactically valid object identifier)</li>
<p>Requesting non existent resources will result in a
<code>404 Not Found</code> HTTP response. Example:</p>
<ul>
<li>
<ahref="/api/1/content/0123456789abcdef0123456789abcdef01234567/"class="uri">/api/1/content/0123456789abcdef0123456789abcdef01234567/</a> (error: no object with that identifier is available [yet?])</li>