diff --git a/api/docs/api.rst b/api/docs/api.rst --- a/api/docs/api.rst +++ b/api/docs/api.rst @@ -1,22 +1,86 @@ Graph traversal API =================== +Semantics +--------- + +The API uses the following semantics to refer to the graph: + +- **Individual node**: as a `Software Heritage persistent identifier + `_. +- **Node type**: as the 3-letter specifier from its persistent identifier + (``cnt``, ``dir``, ``rel``, ``rev``, ``snp``), or as ``*`` for all node + types. +- **Edge type**: as a comma-separated list of ``src:dst`` strings where ``src`` + and ``dst`` are node types, or as ``*`` for all edge types. + +Examples +~~~~~~~~ + +- ``swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2`` refers to the content + node containing the full text of the GPL3 license. +- ``swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35`` refers to the commit in + Linux that merged the 'x86/urgent' branch on 31 December 2017. +- ``"dir:dir,dir:cnt"`` refers to edges which are from directories to + directories nodes, or directories to contents nodes. +- ``"rev:rev,dir:*"`` refers to edges which are from revisions to revisions + nodes, or starting from a directory node. +- ``"*:rel"`` refers to all edges which end nodes are releases. + +Walk +---- + +.. http:get:: /graph/walk/:src/:dst + + Performs a graph traversal and returns the first found path from source to + destination (ending point included). + + :param string src: individual starting node + :param string dst: the traversal will stop at the first node encountered + matching the desired destination (either an individual node or a node type) + + :query string edges: edges types the traversal can follow, default to + ``"*"`` + :query string traversal: can be either ``dfs`` or ``bfs``, default to + ``dfs`` + :query string direction: can be either ``forward`` or ``backward``, default + to ``forward`` + + :statuscode 200: no error + :statuscode 400: an invalid query string has been provided + :statuscode 404: requested starting node cannot be found in the graph + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + [ + "swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35", + "swh:1:rev:52c90f2d32bfa7d6eccd66a56c44ace1f78fbadd", + "swh:1:rev:cea92e843e40452c08ba313abc39f59efbb4c29c", + "swh:1:rev:8d517bdfb57154b8a11d7f1682ecc0f79abf8e02", + ... + ] + Visit ----- -.. http:get:: /graph/visit/:swh_id +.. http:get:: /graph/visit/:src/:dst - Performs a graph traversal and returns explored paths (in the order of the - traversal). + Returns all explored paths and nodes (in the order of the traversal), from + source to destination. - :param string swh_id: starting point for the traversal, represented as a - `Software Heritage persitent identifier + :param string src: starting point for the traversal, represented as a + `Software Heritage persistent identifier `_ + :param string dst: ending point for the traversal, represented either as a + Software Heritage persistent identifier, or as an object type in which case + the traversal will stop on any node with same type. :query string edges: edges types the traversal can follow, expressed as a comma-separated list of ``src:dst`` strings (e.g.: ``"rev:rev,rev:dir"``). If no string is provided, the traversal will use all types of edges. - :query string traversal: default to ``dfs`` :query string direction: can be either ``forward`` or ``backward``, default to ``forward`` @@ -32,14 +96,23 @@ { "paths": [ [ - "swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2", + "swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35", + "swh:1:rev:52c90f2d32bfa7d6eccd66a56c44ace1f78fbadd", ... ], [ - "swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505", + "swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35", + "swh:1:rev:a31e58e129f73ab5b04016330b13ed51fde7a961", ... ], ... + ], + "nodes": [ + "swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35", + "swh:1:rev:52c90f2d32bfa7d6eccd66a56c44ace1f78fbadd", + ... + "swh:1:rev:a31e58e129f73ab5b04016330b13ed51fde7a961", + ... ] }