swh.web.api.views.metadata module#

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

Bases: Field

A DRF field to handle metadata authorities.

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: MetadataAuthority) → str[source]#

Serialize value.

Parameters:

value – a MetadataAuthority

Returns:

A metadata authority identifier, formatted as type IRI

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

From type IRI to MetadataAuthority.

Handles serialization and validation of a metadata authority.

Parameters:

data – A metadata authority identifier, formatted as type IRI

Raises:

serializers.ValidationError – invalid value (missing space, invalid type).

Returns:

A MetadataAuthority

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

Bases: Serializer

Raw Extrinsic Metadata 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.metadata.api_raw_extrinsic_metadata_swhid(request: Request, target: str, validated_query_params: dict[str, Any])[source]#
GET /api/1/raw-extrinsic-metadata/swhid/(target)#

Returns raw extrinsic metadata collected on a given object.

Parameters:

  • target (string) – The core SWHID of the object whose metadata should be returned

Query Parameters:

  • authority (string) – A metadata authority identifier, formatted as <type> <IRI>. Required.

  • after (string) – ISO8601 representation of the minimum timestamp of metadata to fetch. Defaults to allowing all metadata.

  • limit (int) – Maximum number of metadata objects to return (default to 100).

  • page_token (string) – optional opaque token, used to get the next page of results

Request Headers:

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

Response Headers:
Response JSON Array of Objects:

  • target (string) – SWHID of the object described by this metadata (absent when target is not a core SWHID (ie. it does not have type cnt/dir/rev/rel/snp)

  • discovery_date (string) – ISO8601/RFC3339 timestamp of the moment this metadata was collected.

  • authority (object) – authority this metadata is coming from

  • fetcher (object) – tool used to fetch the metadata

  • format (string) – short identifier of the format of the metadata

  • metadata_url (string) – link to download the metadata “blob” itself

  • origin (string) – URL of the origin in which context’s the metadata is valid, if any

  • visit (int) – identifier of the visit in which context’s the metadata is valid, if any

  • snapshot (string) – SWHID of the snapshot in which context’s the metadata is valid, if any

  • release (string) – SWHID of the release in which context’s the metadata is valid, if any

  • revision (string) – SWHID of the revision in which context’s the metadata is valid, if any

  • path (string) – SWHID of the path in which context’s is valid if any, relative to a release or revision as anchor

  • directory (string) – SWHID of the directory in which context’s the metadata is valid, if any

Status Codes:

Example:

https://archive.softwareheritage.org/api/1/raw-extrinsic-metadata/swhid/swh:1:dir:a2faa28028657859c16ff506924212b33f0e1307/?authority=forge%20https://pypi.org/
swh.web.api.views.metadata.api_raw_extrinsic_metadata_get(request: Request, id: str)[source]#
swh.web.api.views.metadata.api_raw_extrinsic_metadata_swhid_authorities(request: Request, target: str)[source]#
GET /api/1/raw-extrinsic-metadata/swhid/(target)/authorities/#

Returns a list of metadata authorities that provided metadata on the given target. They can then be used to get the raw extrinsic metadata collected on that object from each of the authorities.

This endpoint should only be used directly to retrieve metadata from core SWHIDs (with type cnt, dir, rev, rel, and snp). For “extended” SWHIDs such as origins, GET /api/1/raw-extrinsic-metadata/origin/(origin_url)/authorities/ should be used instead of building this URL directly.

Parameters:

  • target (string) – The core SWHID of the object whose metadata-providing authorities should be returned

Request Headers:

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

Response Headers:
Response JSON Array of Objects:

  • type (string) – Type of authority (deposit_client, forge, registry)

  • url (string) – Unique IRI identifying the authority

  • metadata_list_url (object) – URL to get the list of metadata objects on the given object from this authority

Status Codes:

Example:

https://archive.softwareheritage.org/api/1/raw-extrinsic-metadata/swhid/swh:1:dir:a2faa28028657859c16ff506924212b33f0e1307/authorities/
swh.web.api.views.metadata.api_raw_extrinsic_metadata_origin_authorities(request: Request, origin_url: str)[source]#
GET /api/1/raw-extrinsic-metadata/origin/(origin_url)/authorities/#

Similar to GET /api/1/raw-extrinsic-metadata/swhid/(target)/authorities/ but to get metadata on origins instead of objects

Parameters:

  • origin_url (string) – The URL of the origin whose metadata-providing authorities should be returned

Request Headers:

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

Response Headers:
Response JSON Array of Objects:

  • type (string) – Type of authority (deposit_client, forge, registry)

  • url (string) – Unique IRI identifying the authority

  • metadata_list_url (object) – URL to get the list of metadata objects on the given object from this authority

Status Codes:

Example:

https://archive.softwareheritage.org/api/1/raw-extrinsic-metadata/origin/https://github.com/rdicosmo/parmap/authorities/