ArangoDB Manual Pages


REST Interface for Edges
This is an introduction to ArangoDB's REST interface for edges.

ArangoDB offers also some graph functionality. A graph consists of nodes, edges and properties. ArangoDB stores the information how the nodes relate to each other aside from the properties.

A graph data model always consists of two collections: the relations between the nodes in the graphs are stored in an "edges collection", the nodes in the graph are stored in documents in regular collections.

Example:

  • the "edge" collection stores the information that a company's reception is sub-unit to the services unit and the services unit is sub-unit to the CEO. You would express this relationship with the _from and _to property
  • the "normal" collection stores all the properties about the reception, e.g. that 20 people are working there and the room number etc.
  • _from is the document handle of the linked vertex (incoming relation),
  • _to is the document handle of the linked vertex (outgoing relation).

Documents, Identifiers, Handles

Edge: Edges in ArangoDB are special documents. In addition to the internal attributes _key, _id and _rev, they have two attributes _from and _to, which contain document handles, namely the start-point and the end-point of the edge.The values of _from and _to are immutable once saved.

Address and ETag of an Edge

All documents in ArangoDB have a document handle. This handle uniquely defines a document and is managed by ArangoDB. All documents are found under the URI

http://server:port/_api/document/document-handle

For edges you can use the special address

http://server:port/_api/edge/document-handle

For example: Assume that the document handle, which is stored in the _id attribute of the edge, is demo/362549736, then the URL of that edge is:

http://localhost:8529/_api/edge/demo/362549736

Working with Edges using REST

GET /_api/edge
(reads an edge)
GET /_api/edge/document-handle

See REST Interface for Documents for details.

POST /_api/edge
(creates an edge)
POST /_api/edge?collection=collection-name&from= from-handle&to= to-handle
Creates a new edge in the collection identified by collection-name. A JSON representation of the edge document must be passed as the body of the POST request. This JSON object may contain the edge's document key in the _key attribute if needed. The document handle of the start point must be passed in from-handle. The document handle of the end point must be passed in to-handle.from-handle and to-handle are immutable once the edge has been created.In all other respects the method works like POST /document, see REST Interface for Documents for details.
Examples
Create an edge:
> curl --data @- -X POST --dump - http://localhost:8529/_api/edge?collection=7848004&from=7848004/9289796&to=7848004/9355332
{ "e" : 1 }

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
etag: "9683012"

{
  "_rev": "9683012",
  "_id": "7848004/9683012",
  "error": false
}
Read an edge:
> curl -X GET --dump - http://localhost:8529/_api/edge/7848004/9683012

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: "9683012"

{
  "_from": "7848004/9289796",
  "_rev": "9683012",
  "_to": "7848004/9355332",
  "_id": "7848004/9683012",
  "e": 1
}

PUT /_api/edge
(updates an edge)
PUT /_api/edge/document-handle

See REST Interface for Documents for details.

DELETE /_api/edge
(deletes an edge)
DELETE /_api/edge/document-handle

See REST Interface for Documents for details.

GET /_api/edge
(reads an edge header)
HEAD /_api/edge/document-handle

See REST Interface for Documents for details.

GET /_api/edges
(reads in- or outbound edges)
GET /_api/edges/collection-identifier?vertex= vertex-handle&direction=any
Returns the list of edges starting or ending in the vertex identified by vertex-handle.
GET /_api/edges/collection-identifier?vertex= vertex-handle&direction=in
Returns the list of edges ending in the vertex identified by vertex-handle.
GET /_api/edges/collection-identifier?vertex= vertex-handle&direction=out
Returns the list of edges starting in the vertex identified by vertex-handle.
Examples
Any direction
> curl -X GET --dump - http://localhost:8529/_api/edges/17501660?vertex=17501660/18419164

HTTP/1.1 200 OK
content-type: application/json

{
  "edges": [
    {
      "_from": "17501660/18419164",
      "_rev": "19140060",
      "_to": "17501660/19008988",
      "_id": "17501660/19140060"
    },
    {
      "_from": "17501660/18419164",
      "_rev": "19336668",
      "_to": "17501660/19008988",
      "_id": "17501660/19336668",
      "e": 1
    },
    {
      "_from": "17501660/19008988",
      "_rev": "19402204",
      "_to": "17501660/18419164",
      "_id": "17501660/19402204",
      "e": 2
    }
  ],
  "code": 200,
  "error": false
}
In edges
> curl -X GET --dump - http://localhost:8529/_api/edges/17501660?vertex=17501660/18419164&direction=in

HTTP/1.1 200 OK
content-type: application/json

{
  "edges": [
    {
      "_from": "17501660/19008988",
      "_rev": "19402204",
      "_to": "17501660/18419164",
      "_id": "17501660/19402204",
      "e": 2
    }
  ],
  "code": 200,
  "error": false
}
Out edges
> curl -X GET --dump - http://localhost:8529/_api/edges/17501660?vertex=17501660/18419164&direction=out

HTTP/1.1 200 OK
content-type: application/json

{
  "edges": [
    {
      "_from": "17501660/18419164",
      "_rev": "19336668",
      "_to": "17501660/19008988",
      "_id": "17501660/19336668",
      "e": 1
    },
    {
      "_from": "17501660/18419164",
      "_rev": "19140060",
      "_to": "17501660/19008988",
      "_id": "17501660/19140060"
    }
  ],
  "code": 200,
  "error": false
}