You can jump directly to the - - endpoint index - , which lists all available API functionalities, or read on for more general information about the API.
++ 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 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 is - v1.
+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.
+ 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/.
++ 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.
+ 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.
+ 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,revisionWhile 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:
+ 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:
+ 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.
+ 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.
+
+ 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:
+ 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=2To navigate through paginated results, a
- Link HTTP response header is available to link the current result page to the next one. Example:
+ 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:
++ 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 hourX-RateLimit-Limit: maximum number of permitted requests per hour
+
X-RateLimit-Remaining: number of permitted requests remaining before the next resetX-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-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{{ request.method }} {{ request.build_absolute_uri }}
- {{ status_code }}
- {% endif %}
- {% if headers_data %}
- {{ header_name }} {{ header_value | urlize_header_links | safe }}
- {% endfor %}
- {% endif %}
- {{ response_data | urlize_links_and_mails | safe }}| URL | -Allowed Methods | -
|---|
| {{ url.rule | docstring_display | safe }} | -{{ url.methods | dictsort:0 | join:', ' }} | +URL | +Allowed Methods |
|---|
- {% if input_type == 'array' and inputs_list == '' %} - {{ inputs.0.doc | safe }} - {% elif input_type == 'array' and inputs_list != '' %} - an array of objects containing the following keys: - {% elif input_type == 'octet stream' %} - raw data as an octet stream - {% elif input_type == 'object' %} - an object containing the following keys: - {% endif %} - {% if inputs_list != '' %} - {{ inputs_list | docstring_display | safe }} - {% endif %} -
-- {% if return_type == 'array' and returns_list == '' %} - {{ returns.0.doc | safe }} - {% elif return_type == 'array' and returns_list != '' %} - an array of objects containing the following keys: - {% elif return_type == 'octet stream' %} - raw data as an octet stream - {% elif return_type == 'object' %} - an object containing the following keys: - {% endif %} - {% if returns_list != '' %} - {{ returns_list | docstring_display | safe }} - {% endif %} -
-+ {% if input_type == 'array' and inputs_list == '' %} + {{ inputs.0.doc | safe }} + {% elif input_type == 'array' and inputs_list != '' %} + an array of objects containing the following keys: + {% elif input_type == 'octet stream' %} + raw data as an octet stream + {% elif input_type == 'object' %} + an object containing the following keys: + {% endif %} + {% if inputs_list != '' %} + {{ inputs_list | docstring_display | safe }} + {% endif %} +
++ {% if return_type == 'array' and returns_list == '' %} + {{ returns.0.doc | safe }} + {% elif return_type == 'array' and returns_list != '' %} + an array of objects containing the following keys: + {% elif return_type == 'octet stream' %} + raw data as an octet stream + {% elif return_type == 'object' %} + an object containing the following keys: + {% endif %} + {% if returns_list != '' %} + {{ returns_list | docstring_display | safe }} + {% endif %} +