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. | ||||
- **Node restrictions**: a textual specification of which type of nodes can be | |||||
returned after a request. Either ``*`` to denote that all types of nodes can | |||||
be returned or a comma separated list of node types to allow returning only | |||||
those node types. | |||||
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"`` accepted node types returned in the query results. | |||||
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: only return the nodes matching this type; | |||||
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: only return the nodes matching this type; | |||||
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 All 20 Lines | .. http:get:: /graph/randomwalk/:src/:dst | ||||
: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 int limit: limit the number of nodes returned. You can use positive | :query int limit: limit the number of nodes returned. You can use positive | ||||
numbers to get the first N results, or negative numbers to get the last | numbers to get the first N results, or negative numbers to get the last | ||||
N results starting from the tail; | N results starting from the tail; | ||||
default to ``0``, meaning no limit. | default to ``0``, meaning no limit. | ||||
:query integer max_edges: how many edges can be traversed during the visit; | |||||
default to 0 (not restricted) | |||||
:query string return_types: only return the nodes matching this type; | |||||
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 44 Lines • ▼ Show 20 Lines | .. 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 integer max_edges: how many edges can be traversed during the visit; | ||||
can be either ``forward`` or ``backward``, default to ``forward`` | default to 0 (not restricted) | ||||
:query string return_types: only return the nodes matching this type; | |||||
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 134 Lines • Show Last 20 Lines |