swh.web.api.views.extid module#

class swh.web.api.views.extid.ExtidTargetQuerySerializer(*args, **kwargs)[source]#

Bases: Serializer

Extid Target query parameters serializer.

When a field is instantiated, we store the arguments that were used, so that we can present a helpful representation of the object.

validate(data: dict) → dict[source]#

Validate extid_version and extid_type.

extid_version is required if extid_type is defined and vice versa.

Parameters:: data – query parameters
Raises:: serializers.ValidationError – invalid parameters
Returns:: query parameters

swh.web.api.views.extid.api_extid_target(request: Request, swhid: str, validated_query_params: dict)[source]#

GET /api/1/extid/target/(swhid)/#

Get information about external identifiers targeting an archived object.

An external identifier is used by a system that does not fit the Software Heritage data model.

Parameters:

swhid (string) – a SWHID to check if external identifiers target it

Query Parameters:

extid_type (string) – optional external identifier type to use as a filter, must be provided if extid_version parameter is.
extid_version (number) – optional version number of external identifier type, must be provided if extid_type parameter is.
extid_format (string) – the format used to encode an extid to an ASCII string, either base64url, hex or raw (default to hex).

Request Headers:

Accept – the requested response content type, either application/json (default) or application/yaml

Response Headers:

Content-Type – this depends on Accept header of request

Response JSON Array of Objects:

extid_type (string) – the type of the external identifier
extid (string) – the value of the external identifier
target (string) – the SWHID of the archived object targeted by the external identifier
target_url (string) – URL to browse the targeted archived object
extid_version (number) – the version of the external identifier

Status Codes:

200 OK – no error
400 Bad Request – provided parameters are invalid
404 Not Found – external identifier targeting SWHID cannot be found

Example:

https://archive.softwareheritage.org/api/1/extid/target/swh:1:rev:a2903689803b2c07890a930284425838436425a6/?extid_format=raw
https://archive.softwareheritage.org/api/1/extid/target/swh:1:rev:6b29add7cb6b5f6045df308c43e4177f1f854a56/?extid_format=hex

swh.web.api.views.extid.api_extid(request: Request, extid_type: str, extid_format: str, extid: str)[source]#

GET /api/1/extid/(extid_type)/(extid_format):(extid)/#

Get information about an external identifier.

An external identifier is used by a system that does not fit the Software Heritage data model.

As an external identifier is stored in binary into the archive database, the format used to decode its ASCII representation must be explicitly specified. The available formats are the following:

base64url: the external identifier is encoded to base64url.
hex: the external identifier is a checksum in hexadecimal representation
raw: the external identifier is an ASCII string

The types of external identifier that can be requested are given below.

VCS related:

bzr-nodeid: Revision ASCII identifier of a Bazaar repository, to get such identifiers use the following command in your Bazaar repository: bzr log --show-ids.
hg-nodeid: Node hash identifier for the revision of a Mercurial repository, to get such identifier execute the following command in your Mercurial repository: hg id -r <rev_num> --template '{node}'.

Guix and Nix related (must be queried with the extid_version query parameter set to 1 to ensure correctness):

nar-sha256: sha256 checksum of a Nix Archive (NAR), used to deterministically identifies the contents of a source tree (corresponds to recursive hash mode used by Guix and Nix)
checksum-sha256: sha256 checksum of a file, typically a tarball (corresponds to flat hash mode used by Guix and Nix)
checksum-sha512: sha512 checksum of a file, typically a tarball (corresponds to flat hash mode used by Guix and Nix)