Differential D2885 Diff 10276 docs/extrinsic-metadata-specification.rst

Changeset View

Standalone View

docs/extrinsic-metadata-specification.rst

	Show First 20 Lines • Show All 122 Lines • ▼ Show 20 Lines
	* Adding metadata::			* Adding metadata::

	origin_metadata_add(origin_url, discovery_date,			origin_metadata_add(origin_url, discovery_date,
	authority, fetcher,			authority, fetcher,
	format, metadata)			format, metadata)

	which adds a new `metadata` byte string obtained from a given authority			which adds a new `metadata` byte string obtained from a given authority
	and associated to the origin.			and associated to the origin.
	`discovery_date` is an ISO 8601 datetime string.			`discovery_date` is a Python datetime.
	`authority` must be a dict containing keys `type` and `url`, and			`authority` must be a dict containing keys `type` and `url`, and
	`fetcher` a dict containing keys `name` and `version`.			`fetcher` a dict containing keys `name` and `version`.
	The authority and fetcher must be known to the storage before using this			The authority and fetcher must be known to the storage before using this
	endpoint.			endpoint.
	`format` is a text field indicating the format of the content of the			`format` is a text field indicating the format of the content of the
	`metadata` byte string.			`metadata` byte string.

	* Getting latest metadata::			* Getting latest metadata::

	origin_metadata_get_latest(origin_url, authority)			origin_metadata_get_latest(origin_url, authority)

	where `authority` must be a dict containing keys `type` and `url`,			where `authority` must be a dict containing keys `type` and `url`,
	which returns a dictionary corresponding to the latest metadata entry			which returns a dictionary corresponding to the latest metadata entry
	added from this origin, in the format::			added from this origin, in the format::

	{			{
	'authority': {'type': ..., 'url': ...},			'authority': {'type': ..., 'url': ...},
	'fetcher': {'name': ..., 'version': ...},			'fetcher': {'name': ..., 'version': ...},
	'discovery_date': '...',			'discovery_date': ...,
	'format': '...',			'format': '...',
	'metadata': b'...'			'metadata': b'...'
	}			}


	* Getting all metadata::			* Getting all metadata::

	origin_metadata_get(origin_url,			origin_metadata_get(origin_url,
	authority,			authority,
	after, limit)			after, limit)

	which returns a list of dictionaries, one for each metadata item			which returns a list of dictionaries, one for each metadata item
	deposited, corresponding to the given origin and obtained from the			deposited, corresponding to the given origin and obtained from the
	specified authority.			specified authority.
	`authority` must be a dict containing keys `type` and `url`.			`authority` must be a dict containing keys `type` and `url`.

	Each of these dictionaries is in the following format::			Each of these dictionaries is in the following format::

	{			{
	'authority': {'type': ..., 'url': ...},			'authority': {'type': ..., 'url': ...},
	'fetcher': {'name': ..., 'version': ...},			'fetcher': {'name': ..., 'version': ...},
	'discovery_date': '...',			'discovery_date': ...,
	'format': '...',			'format': '...',
	'metadata': b'...'			'metadata': b'...'
	}			}

	The parameters ``after`` and ``limit`` are used for pagination based on the			The parameters ``after`` and ``limit`` are used for pagination based on the
	order defined by the ``discovery_date``.			order defined by the ``discovery_date``.

	``metadata`` is a bytes array (eventually encoded using Base64).			``metadata`` is a bytes array (eventually encoded using Base64).
	Its format is specific to each authority; and is treated as an opaque value			Its format is specific to each authority; and is treated as an opaque value
	by the storage.			by the storage.
	Unifying these various formats into a common language is outside the scope			Unifying these various formats into a common language is outside the scope
	of this specification.			of this specification.