+ You can jump directly to the endpoint index , which + lists all available API functionalities, or read on for more general information about the API. +
+ ++ The Software Heritage project harvests publicly + available source code by tracking software distribution channels such as version control + systems, tarball releases, and distribution packages. +
++ All retrieved source code and related metadata are stored in the Software Heritage archive, that + is conceptually a Merkle DAG. 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. +
++ The following types of objects (i.e., graph nodes) can be found in the Software Heritage archive + (for more information see the Software Heritage + glossary): +
+The current version of the API isv1.
++ Warning: this version of the API is not to be considered stable yet. + Non-backward compatible changes might happen even without changing the API version number. +
+ +API access is over HTTPS.
++ All API endpoints are rooted at + https://archive.softwareheritage.org/api/1/. +
+Data is sent and received as JSON by default.
+Example:
+from the command line:
+curl -i https://archive.softwareheritage.org/api/1/stat/counters/
+ The response format can be overridden using the Accept request header. In
+ particular, Accept: text/html (that web browsers send by default) requests HTML
+ pretty-printing, whereas Accept: application/yaml requests YAML-encoded responses.
+
Example:
+from the command line:
+curl -i -H 'Accept: application/yaml' https://archive.softwareheritage.org/api/1/stat/counters/+ Some API endpoints can be tweaked by passing optional parameters. For GET requests, optional + parameters can be passed as an HTTP query string. +
+
+ The optional parameter fields is accepted by all endpoints that return dictionaries
+ and can be used to restrict the list of fields returned by the API, in case you are not
+ interested in all of them. By default, all available fields are returned.
+
Example:
+from the command line:
+curl https://archive.softwareheritage.org/api/1/stat/counters/?fields=content,directory,revision+ While API endpoints will return different kinds of errors depending on their own semantics, some + error patterns are common across all endpoints. +
+
+ Sending malformed data, including syntactically incorrect object identifiers, will result in a
+ 400 Bad Request HTTP response. Example:
+
from the command line:
+curl -i https://archive.softwareheritage.org/api/1/content/deadbeef/
+ Requesting non existent resources will result in a 404 Not Found HTTP response.
+ Example:
+
from the command line:
+curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/
+ Unavailability of the underlying storage backend will result in a 503 Service
+ Unavailable HTTP response.
+
+ While attempting to decode UTF-8 strings from raw bytes stored in the archive, some errors might
+ happen when generating an API response. In that case, an extra field
+ decoding_failures will be added to each concerned JSON object (possibly nested). It
+ will contain the list of its key names where UTF-8 decoding failed.
+
+ A string that could not be decoded will have the bytes of its invalid UTF-8 sequences escaped as
+ \\x<hex value>.
+
Requests that might potentially return many items will be paginated.
+
+ Page size is set to a default (usually: 10 items), but might be overridden with the
+ per_page query parameter up to a maximum (usually: 50 items). Example:
+
curl https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2
+ To navigate through paginated results, a Link HTTP response header is available to
+ link the current result page to the next one. Example:
+
curl -i https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2 | grep ^Link:
+Link: </api/1/origin/1/visits/?last_visit=2&per_page=2>; rel="next",+ Due to limited resource availability on the back end side, API usage is currently rate limited. + Furthermore, as API usage is currently entirely anonymous (i.e., without any authentication), + API "users" are currently identified by their origin IP address. +
+ ++ Three HTTP response fields will inform you about the current state of limits that apply to your + current rate limiting bucket: +
+X-RateLimit-Limit: maximum number of permitted requests per hour
+ X-RateLimit-Remaining: number of permitted requests remaining before the next
+ reset
+ X-RateLimit-Reset: the time (expressed in Unix
+ time seconds) at which the current rate limiting will expire, resetting to a fresh
+ X-RateLimit-Limit
+ Example:
+curl -i https://archive.softwareheritage.org/api/1/stat/counters/ | grep ^X-RateLimit
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 54
+X-RateLimit-Reset: 1485794532