Changeset View
Changeset View
Standalone View
Standalone View
docs/api.rst
Show All 25 Lines | - **Edge restrictions**: a textual specification of which edges can be followed | ||||
are reversed too. So, for instance, ``ori:snp`` makes sense when traversing | are reversed too. So, for instance, ``ori:snp`` makes sense when traversing | ||||
the forward graph, but useless (due to lack of matching edges in the graph) | the forward graph, but useless (due to lack of matching edges in the graph) | ||||
when traversing the backward graph; conversely ``snp:ori`` is useful when | when traversing the backward graph; conversely ``snp:ori`` is useful when | ||||
traversing the backward graph, but not in the forward one. For the same | traversing the backward graph, but not in the forward one. For the same | ||||
reason ``dir:dir`` allows following edges from parent directories to | reason ``dir:dir`` allows following edges from parent directories to | ||||
sub-directories when traversing the forward graph, but the same restriction | sub-directories when traversing the forward graph, but the same restriction | ||||
allows following edges from sub-directories to parent directories. | allows following edges from sub-directories to parent directories. | ||||
We can also specify how many edges a visit can traversed, in order to avoid Dos. | |||||
- **Node filtering**: a textual specification of which type of nodes can be printed after a request. | |||||
Either ``*`` to denote that all types of nodes can be printed or a comma separated list of | |||||
node types to allow following only those nodes. | |||||
Examples | Examples | ||||
~~~~~~~~ | ~~~~~~~~ | ||||
- ``swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2`` the SWHID of a node of | - ``swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2`` the SWHID of a node of | ||||
type content containing the full text of the GPL3 license. | type content containing the full text of the GPL3 license. | ||||
- ``swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35`` the SWHID of a node of | - ``swh:1:rev:f39d7d78b70e0f39facb1e4fab77ad3df5c52a35`` the SWHID of a node of | ||||
type revision corresponding to the commit in Linux that merged the | type revision corresponding to the commit in Linux that merged the | ||||
'x86/urgent' branch on 31 December 2017. | 'x86/urgent' branch on 31 December 2017. | ||||
- ``"dir:dir,dir:cnt"`` node types allowing edges from directories to | - ``"dir:dir,dir:cnt"`` node types allowing edges from directories to | ||||
directories nodes, or directories to contents nodes. | directories nodes, or directories to contents nodes. | ||||
- ``"rev:rev,dir:*"`` node types allowing edges from revisions to revisions | - ``"rev:rev,dir:*"`` node types allowing edges from revisions to revisions | ||||
nodes, or from directories nodes. | nodes, or from directories nodes. | ||||
- ``"*:rel"`` node types allowing all edges to releases. | - ``"*:rel"`` node types allowing all edges to releases. | ||||
- ``"cnt,snp"`` node types allowed the swhid of content and snapshot nodes to be printed in the request response. | |||||
Leaves | Leaves | ||||
------ | ------ | ||||
.. http:get:: /graph/leaves/:src | .. http:get:: /graph/leaves/:src | ||||
Performs a graph traversal and returns the leaves of the subgraph rooted at | Performs a graph traversal and returns the leaves of the subgraph rooted at | ||||
the specified source node. | the specified source node. | ||||
:param string src: source node specified as a SWHID | :param string src: source node specified as a SWHID | ||||
:query string edges: edges types the traversal can follow; default to | :query string edges: edges types the traversal can follow; default to | ||||
``"*"`` | ``"*"`` | ||||
:query string direction: direction in which graph edges will be followed; | :query string direction: direction in which graph edges will be followed; | ||||
can be either ``forward`` or ``backward``, default to ``forward`` | can be either ``forward`` or ``backward``, default to ``forward`` | ||||
:query integer max_edges: how many edges can be traversed during the visit; default to 0 (not restricted) | |||||
:query string return_types: types of nodes we want to be displayed; default to ``"*"`` | |||||
:statuscode 200: success | :statuscode 200: success | ||||
:statuscode 400: invalid query string provided | :statuscode 400: invalid query string provided | ||||
:statuscode 404: starting node cannot be found | :statuscode 404: starting node cannot be found | ||||
**Example:** | **Example:** | ||||
.. sourcecode:: http | .. sourcecode:: http | ||||
Show All 22 Lines | .. http:get:: /graph/neighbors/:src | ||||
Returns node direct neighbors (linked with exactly one edge) in the graph. | Returns node direct neighbors (linked with exactly one edge) in the graph. | ||||
:param string src: source node specified as a SWHID | :param string src: source node specified as a SWHID | ||||
:query string edges: edges types allowed to be listed as neighbors; default | :query string edges: edges types allowed to be listed as neighbors; default | ||||
to ``"*"`` | to ``"*"`` | ||||
:query string direction: direction in which graph edges will be followed; | :query string direction: direction in which graph edges will be followed; | ||||
can be either ``forward`` or ``backward``, default to ``forward`` | can be either ``forward`` or ``backward``, default to ``forward`` | ||||
:query integer max_edges: how many edges can be traversed during the visit; default to 0 (not restricted) | |||||
:query string return_types: types of nodes we want to be displayed; default to ``"*"`` | |||||
:statuscode 200: success | :statuscode 200: success | ||||
:statuscode 400: invalid query string provided | :statuscode 400: invalid query string provided | ||||
:statuscode 404: starting node cannot be found | :statuscode 404: starting node cannot be found | ||||
**Example:** | **Example:** | ||||
.. sourcecode:: http | .. sourcecode:: http | ||||
Show All 28 Lines | .. http:get:: /graph/walk/:src/:dst | ||||
the desired destination. | the desired destination. | ||||
:query string edges: edges types the traversal can follow; default to | :query string edges: edges types the traversal can follow; default to | ||||
``"*"`` | ``"*"`` | ||||
:query string traversal: traversal algorithm; can be either ``dfs`` or | :query string traversal: traversal algorithm; can be either ``dfs`` or | ||||
``bfs``, default to ``dfs`` | ``bfs``, default to ``dfs`` | ||||
:query string direction: direction in which graph edges will be followed; | :query string direction: direction in which graph edges will be followed; | ||||
can be either ``forward`` or ``backward``, default to ``forward`` | can be either ``forward`` or ``backward``, default to ``forward`` | ||||
:query string return_types: types of nodes we want to be displayed; default to ``"*"`` | |||||
:statuscode 200: success | :statuscode 200: success | ||||
:statuscode 400: invalid query string provided | :statuscode 400: invalid query string provided | ||||
:statuscode 404: starting node cannot be found | :statuscode 404: starting node cannot be found | ||||
**Example:** | **Example:** | ||||
.. sourcecode:: http | .. sourcecode:: http | ||||
▲ Show 20 Lines • Show All 70 Lines • ▼ Show 20 Lines | .. sourcecode:: http | ||||
swh:1:ori:98aa0e71f5c789b12673717a97f6e9fa20aa1161 | swh:1:ori:98aa0e71f5c789b12673717a97f6e9fa20aa1161 | ||||
swh:1:snp:a511810642b7795e725033febdd82075064ed863 | swh:1:snp:a511810642b7795e725033febdd82075064ed863 | ||||
Visit | Visit | ||||
----- | ----- | ||||
.. http:get:: /graph/visit/nodes/:src | .. http:get:: /graph/visit/nodes/:src | ||||
:query string return_types: types of nodes we want to be displayed; default to ``"*"`` | |||||
.. http:get:: /graph/visit/edges/:src | .. http:get:: /graph/visit/edges/:src | ||||
.. http:get:: /graph/visit/paths/:src | .. http:get:: /graph/visit/paths/:src | ||||
Performs a graph traversal and returns explored nodes, edges or paths (in | Performs a graph traversal and returns explored nodes, edges or paths (in | ||||
the order of the traversal). | the order of the traversal). | ||||
:param string src: starting node specified as a SWHID | :param string src: starting node specified as a SWHID | ||||
:query string edges: edges types the traversal can follow; default to | :query string edges: edges types the traversal can follow; default to | ||||
``"*"`` | ``"*"`` | ||||
:query string direction: direction in which graph edges will be followed; | :query string direction: direction in which graph edges will be followed; | ||||
can be either ``forward`` or ``backward``, default to ``forward`` | can be either ``forward`` or ``backward``, default to ``forward`` | ||||
:query integer max_edges: how many edges can be traversed during the visit; default to 0 (not restricted) | |||||
:statuscode 200: success | :statuscode 200: success | ||||
:statuscode 400: invalid query string provided | :statuscode 400: invalid query string provided | ||||
:statuscode 404: starting node cannot be found | :statuscode 404: starting node cannot be found | ||||
**Example:** | **Example:** | ||||
.. sourcecode:: http | .. sourcecode:: http | ||||
▲ Show 20 Lines • Show All 134 Lines • Show Last 20 Lines |