swh.web.api.views.snapshot module#

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

Bases: Field

A DRF field to handle snapshot target types.

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

to_representation(value: list[str]) → str[source]#

Serialize value.

Parameters:

value – a list of target types

Returns:

A comma separated list of target types

to_internal_value(data: str) → list[str][source]#

From a comma separated string to a list.

Handles serialization and validation of the target types requested.

Parameters:

data – a comma separated string of target types

Raises:

serializers.ValidationError – one or more target types are not valid.

Returns:

A list of target types

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

Bases: Serializer

Snapshot 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.

swh.web.api.views.snapshot.api_snapshot(request: Request, snapshot_id: str, validated_query_params: dict[str, Any])[source]#
GET /api/1/snapshot/(snapshot_id)/#

Get information about a snapshot in the archive.

A snapshot is a set of named branches, which are pointers to objects at any level of the Software Heritage DAG. It represents a full picture of an origin at a given time.

As well as pointing to other objects in the Software Heritage DAG, branches can also be aliases, in which case their target is the name of another branch in the same snapshot, or dangling, in which case the target is unknown.

A snapshot identifier is a salted sha1. See swh.model.git_objects.snapshot_git_object() in our data model module for details about how they are computed.

Parameters:

  • snapshot_id (sha1) – a snapshot identifier

Query Parameters:

  • branches_from (str) – optional parameter used to skip branches whose name is lesser than it before returning them

  • branches_count (int) – optional parameter used to restrain the amount of returned branches (default to 1000)

  • target_types (str) – optional comma separated list parameter used to filter the target types of branch to return (possible values that can be contained in that list are content, directory, revision, release, snapshot or alias)

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

  • Link – indicates that a subsequent result page is available and contains the url pointing to it

Response JSON Object:

  • branches (object) – object containing all branches associated to the snapshot,for each of them the associated target type and id are given but also a link to get information about that target

  • id (string) – the unique identifier of the snapshot

Status Codes:

  • 200 OK – no error

  • 400 Bad Request – an invalid snapshot identifier or invalid query parameters has been provided

  • 404 Not Found – requested snapshot cannot be found in the archive

Example:

https://archive.softwareheritage.org/api/1/snapshot/6a3a2cf0b2b90ce7ae1cf0a221ed68035b686f5a/