From f58f4c2e7ff484ef1018e1a7e9d9772a3f6ce7c2 Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli <zack@upsilon.cc> Date: Mon, 15 Oct 2018 17:31:13 +0200 Subject: [PATCH] doc: document PID resolution possibilities other than Web UI / Promote "Resolution" to a new top-level section, because it's now rather voluminous. As part of this document the resolver limitations of identifiers.org, that get in the way of PID contextual information. Closes T1015 Closes T1223 --- docs/persistent-identifiers.rst | 68 ++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/docs/persistent-identifiers.rst b/docs/persistent-identifiers.rst index 29bf797e..a5570ce1 100644 --- a/docs/persistent-identifiers.rst +++ b/docs/persistent-identifiers.rst @@ -128,23 +128,6 @@ Examples of the entire Darktable Git repository taken on 4 May 2017 from GitHub -Resolution ----------- - -Persistent identifiers can be resolved using the Software Heritage Web -application (see :py:mod:`swh.web`). - -In particular, the root endpoint ``/`` can be given a persistent identifier and -will lead to the browsing page of the corresponding object, like this: -``https://archive.softwareheritage.org/<identifier>``. For example: - -* `<https://archive.softwareheritage.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_ -* `<https://archive.softwareheritage.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_ -* `<https://archive.softwareheritage.org/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_ -* `<https://archive.softwareheritage.org/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_ -* `<https://archive.softwareheritage.org/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_ - - Contextual information ====================== @@ -191,3 +174,54 @@ The following piece of contextual information are supported: * software origin: where a given object has been found or observed in the wild, as the URI that was used by Software Heritage to ingest the object into the archive + + +Resolution +========== + + +Dedicated resolvers +------------------- + +Persistent identifiers can be resolved using the Software Heritage Web +application (see :py:mod:`swh.web`). In particular, the **root endpoint** +``/`` can be given a persistent identifier and will lead to the browsing page +of the corresponding object, like this: +``https://archive.softwareheritage.org/<identifier>``. + +A **dedicated ``/resolve`` endpoint** of the HTTP API is also available to +explicitly request persistent identifier resolution; see: +:http:get:`/api/1/resolve/(swh_id)/`. + +Examples: + +* `<https://archive.softwareheritage.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_ +* `<https://archive.softwareheritage.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_ +* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_ +* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_ +* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_ + + +External resolvers +------------------ + +The following **independent resolvers** support resolution of Software +Heritage persistent identifiers: + +* `Identifiers.org <https://identifiers.org>`_; see: + `<http://identifiers.org/swh/>`_ (registry identifier `MIR:00000655 + <https://www.ebi.ac.uk/miriam/main/datatypes/MIR:00000655>`_). + +* `Name-to-Thing (N2T) <https://n2t.net/>`_ + +Examples: + +* `<https://identifiers.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_ +* `<https://identifiers.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_ +* `<https://identifiers.org/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_ +* `<https://n2t.net/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_ +* `<https://n2t.net/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_ + +Note that resolution via Identifiers.org does not support contextual +information, due to `syntactic incompatibilities +<http://identifiers.org/documentation#custom_requests>`_. -- GitLab