HTTP Interface for Traversals

The API endpoint /_api/traversal is deprecated from version 3.4.0 on.
The preferred way to traverse graphs is with AQL.

ArangoDB's graph traversals are executed on the server. Traversals can be
initiated by clients by sending the traversal description for execution to
the server.

Traversals in ArangoDB are used to walk over a graph stored in one
edge collection.
It can easily be described which edges of the graph should be followed
and which actions should be performed on each visited vertex.
Furthermore the ordering of visiting the nodes can be
specified, for instance depth-first or breadth-first search
are offered.

Executing Traversals via HTTP

executes a traversal

execute a server-side traversal

POST /_api/traversal

This route should no longer be used.
It is considered as deprecated from version 3.4.0 on.
It is superseded by AQL graph traversal.

Starts a traversal starting from a given vertex and following.
edges contained in a given edgeCollection. The request must
contain the following attributes.

A JSON object with these properties is required:

sort: body (JavaScript) code of a custom comparison function
for the edges. The signature of this function is
(l, r) -> integer (where l and r are edges) and must
return -1 if l is smaller than, +1 if l is greater than,
and 0 if l and r are equal. The reason for this is the
following: The order of edges returned for a certain
vertex is undefined. This is because there is no natural
order of edges for a vertex with multiple connected edges.
To explicitly define the order in which edges on the
vertex are followed, you can specify an edge comparator
function with this attribute. Note that the value here has
to be a string to conform to the JSON standard, which in
turn is parsed as function body on the server side. Furthermore
note that this attribute is only used for the standard
expanders. If you use your custom expander you have to
do the sorting yourself within the expander code.

direction: direction for traversal

if set, must be either "outbound", "inbound", or "any"

if not set, the expander attribute must be specified

minDepth: ANDed with any existing filters):
visits only nodes in at least the given depth

startVertex: id of the startVertex, e.g. "users/foo".

visitor: body (JavaScript) code of custom visitor function
function signature: (config, result, vertex, path, connected) -> void
The visitor function can do anything, but its return value is ignored. To
populate a result, use the result variable by reference. Note that the
connected argument is only populated when the order attribute is set
to "preorder-expander".

Array -> containing any combination of the above.
If there is at least one "exclude" or "prune" respectively
is contained, it's effect will occur.

init: body (JavaScript) code of custom result initialization function
function signature: (config, result) -> void
initialize any values in result with what is required

maxIterations: Maximum number of iterations in each traversal. This number can be
set to prevent endless loops in traversal of cyclic graphs. When a traversal performs
as many iterations as the maxIterations value, the traversal will abort with an
error. If maxIterations is not set, a server-defined value may be used.

maxDepth: ANDed with any existing filters visits only nodes in at most the given depth

uniqueness: specifies uniqueness for vertices and edges visited.
If set, must be an object like this:
"uniqueness": {"vertices": "none"|"global"|"path", "edges": "none"|"global"|"path"}

order: traversal order can be "preorder", "postorder" or "preorder-expander"

graphName: name of the graph that contains the edges.
Either edgeCollection or graphName has to be given.
In case both values are set the graphName is preferred.

expander: body (JavaScript) code of custom expander function
must be set if direction attribute is not set
function signature: (config, vertex, path) -> array
expander must return an array of the connections for vertex
each connection is an object with the attributes edge and vertex

edgeCollection: name of the collection that contains the edges.

If the Traversal is successfully executed HTTP 200 will be returned.
Additionally the result object will be returned by the traversal.

For successful traversals, the returned JSON object has the
following properties:

error: boolean flag to indicate if an error occurred (false
in this case)

code: the HTTP status code

result: the return value of the traversal

If the traversal specification is either missing or malformed, the server
will respond with HTTP 400.

The body of the response will then contain a JSON object with additional error
details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)

code: the HTTP status code

errorNum: the server error number

errorMessage: a descriptive error message

Return Codes

200:
If the traversal is fully executed
HTTP 200 will be returned.

400:
If the traversal specification is either missing or malformed, the server
will respond with HTTP 400.

404:
The server will responded with HTTP 404 if the specified edge collection
does not exist, or the specified start vertex cannot be found.

500:
The server will responded with HTTP 500 when an error occurs inside the
traversal or if a traversal performs more than maxIterations iterations.

Examples

In the following examples the underlying graph will contain five persons
Alice, Bob, Charlie, Dave and Eve.
We will have the following directed relations: