Handling Edges

Examples will explain the REST API for manipulating edges of the graph module on the knows graph:

Create an edge

Creates an edge in an existing graph

POST /_api/gharial/{graph}/edge/{collection}

Path Parameters

• graph (string, required): The name of the graph.

• collection (string, required): The name of the edge collection the edge belongs to.

Query Parameters

• waitForSync (boolean, optional): Define if the request should wait until synced to disk.

• returnNew (boolean, optional): Define if the response should contain the complete new version of the document.

Request Body

• _from (string, required): The source vertex of this edge. Has to be valid within the used edge definition.

• _to (string, required): The target vertex of this edge. Has to be valid within the used edge definition.

Creates a new edge in the collection. Within the body the edge has to contain a _from and _to value referencing to valid vertices in the graph. Furthermore the edge has to be valid in the definition of the used edge collection.

Responses

HTTP 201: Returned if the edge could be created and waitForSync is true.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The internal attributes for the edge.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 202: Returned if the request was successful but waitForSync is false.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The internal attributes for the edge.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 400: Returned if the input document is invalid. This can for instance be the case if the _from or _to attribute is missing or malformed, or if the referenced vertex collection is not part of the graph.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 403: Returned if your user has insufficient rights. In order to insert edges into the graph you at least need to have the following privileges:

1. Read Only access on the Database.
2. Write access on the given collection.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 404: Returned in any of the following cases:

• no graph with this name could be found.
• the edge collection is not part of the graph.
• the vertex collection is part of the graph, but does not exist.

• _from or _to vertex does not exist.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occurred.

  • errorMessage (string): A message created for this error.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation <<EOF
{ 
  "type" : "friend", 
  "_from" : "female/alice", 
  "_to" : "female/diana" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 94
etag: _eLYz89m---
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 202, 
  "edge" : { 
    "_id" : "relation/65288", 
    "_key" : "65288", 
    "_rev" : "_eLYz89m---" 
  } 
}

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation <<EOF
{ 
  "type" : "friend", 
  "_from" : "female/alice", 
  "_to" : "female/diana" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 94
etag: _eLYz89m---
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Get an edge

fetch an edge

GET /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

• graph (string, required): The name of the graph.

• collection (string, required): The name of the edge collection the edge belongs to.

• edge (string, required): The _key attribute of the edge.

Query Parameters

• rev (string, optional): Must contain a revision. If this is set a document is only returned if it has exactly this revision. Also see if-match header as an alternative to this.

Header Parameters

• if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is returned, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

• if-none-match (string, optional): If the “If-None-Match” header is given, then it must contain exactly one Etag. The document is returned, only if it has a different revision as the given Etag. Otherwise a HTTP 304 is returned.

Gets an edge from the given collection.

Responses

HTTP 200: Returned if the edge could be found.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The complete edge.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 304: Returned if the if-none-match header is given and the currently stored edge still has this revision value. So there was no update between the last time the edge was fetched by the caller.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 403: Returned if your user has insufficient rights. In order to update vertices in the graph you at least need to have the following privileges:

1. Read Only access on the Database.
2. Read Only access on the given collection.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

• No graph with this name could be found.
• This collection is not part of the graph.

• The edge does not exist.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occurred.

  • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/edge/relation/65926

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 172
etag: _eLYz9Bu--_
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "edge" : { 
    "_key" : "65926", 
    "_id" : "relation/65926", 
    "_from" : "male/charly", 
    "_to" : "female/diana", 
    "_rev" : "_eLYz9Bu--_", 
    "type" : "married", 
    "vertex" : "charly" 
  } 
}

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/edge/relation/65926

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 172
etag: _eLYz9Bu--_
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Examples will explain the API on the social graph:

Modify an edge

modify an existing edge

PATCH /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

• graph (string, required): The name of the graph.

• collection (string, required): The name of the edge collection the edge belongs to.

• edge (string, required): The _key attribute of the vertex.

Query Parameters

• waitForSync (boolean, optional): Define if the request should wait until synced to disk.

• keepNull (boolean, optional): Define if values set to null should be stored. By default (true) the given documents attribute(s) will be set to null. If this parameter is false the attribute(s) will instead be deleted from the document.

• returnOld (boolean, optional): Define if a presentation of the deleted document should be returned within the response object.

• returnNew (boolean, optional): Define if a presentation of the new document should be returned within the response object.

Header Parameters

• if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is updated, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

Request Body

(object, required)

The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged.

Updates the data of the specific edge in the collection.

Responses

HTTP 200: Returned if the edge could be updated, and waitForSync is false.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The internal attributes for the edge.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 202: Returned if the request was successful but waitForSync is false.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The internal attributes for the edge.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 403: Returned if your user has insufficient rights. In order to update edges in the graph you at least need to have the following privileges:

1. Read Only access on the Database.
2. Write access on the given collection.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

• No graph with this name could be found.
• This collection is not part of the graph.
• The edge to update does not exist.

• either _from or _to vertex does not exist (if updated).

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occurred.

  • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

Examples

shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation/66441 <<EOF
{ 
  "since" : "01.01.2001" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 118
etag: _eLYz9E2---
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 202, 
  "edge" : { 
    "_id" : "relation/66441", 
    "_key" : "66441", 
    "_oldRev" : "_eLYz9Ey--E", 
    "_rev" : "_eLYz9E2---" 
  } 
}

shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation/66441 <<EOF
{ 
  "since" : "01.01.2001" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 118
etag: _eLYz9E2---
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Replace an edge

replace the content of an existing edge

PUT /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

• graph (string, required): The name of the graph.

• collection (string, required): The name of the edge collection the edge belongs to.

• edge (string, required): The _key attribute of the vertex.

Query Parameters

• waitForSync (boolean, optional): Define if the request should wait until synced to disk.

• keepNull (boolean, optional): Define if values set to null should be stored. By default the key is not removed from the document.

• returnOld (boolean, optional): Define if a presentation of the deleted document should be returned within the response object.

• returnNew (boolean, optional): Define if a presentation of the new document should be returned within the response object.

Header Parameters

• if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is updated, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

Request Body

• _from (string, required): The source vertex of this edge. Has to be valid within the used edge definition.

• _to (string, required): The target vertex of this edge. Has to be valid within the used edge definition.

Replaces the data of an edge in the collection.

Responses

HTTP 201: Returned if the request was successful but waitForSync is true.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The internal attributes for the edge

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 202: Returned if the request was successful but waitForSync is false.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• edge (object): The internal attributes for the edge

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

• old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 403: Returned if your user has insufficient rights. In order to replace edges in the graph you at least need to have the following privileges:

1. Read Only access on the Database.
2. Write access on the given collection.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

• No graph with this name could be found.
• This collection is not part of the graph.
• The edge to replace does not exist.

• either _from or _to vertex does not exist.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occurred.

  • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

Examples

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation/66498 <<EOF
{ 
  "type" : "divorced", 
  "_from" : "female/alice", 
  "_to" : "male/bob" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 118
etag: _eLYz9FO--A
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 202, 
  "edge" : { 
    "_id" : "relation/66498", 
    "_key" : "66498", 
    "_oldRev" : "_eLYz9FK--C", 
    "_rev" : "_eLYz9FO--A" 
  } 
}

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation/66498 <<EOF
{ 
  "type" : "divorced", 
  "_from" : "female/alice", 
  "_to" : "male/bob" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 118
etag: _eLYz9FO--A
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Remove an edge

removes an edge from graph

DELETE /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

• graph (string, required): The name of the graph.

• collection (string, required): The name of the edge collection the edge belongs to.

• edge (string, required): The _key attribute of the edge.

Query Parameters

• waitForSync (boolean, optional): Define if the request should wait until synced to disk.

• returnOld (boolean, optional): Define if a presentation of the deleted document should be returned within the response object.

Header Parameters

• if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is updated, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

Removes an edge from the collection.

Responses

HTTP 200: Returned if the edge could be removed.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• removed (boolean): Is set to true if the remove was successful.

• old (object): The complete deleted edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 202: Returned if the request was successful but waitForSync is false.

• error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

• code (integer): The response code.

• removed (boolean): Is set to true if the remove was successful.

• old (object): The complete deleted edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

  • _id (string): The _id value of the stored data.

  • _key (string): The _key value of the stored data.

  • _rev (string): The _rev value of the stored data.

  • _from (string): The _from value of the stored data.

  • _to (string): The _to value of the stored data.

HTTP 403: Returned if your user has insufficient rights. In order to delete vertices in the graph you at least need to have the following privileges:

1. Read Only access on the Database.
2. Write access on the given collection.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

• No graph with this name could be found.
• This collection is not part of the graph.

• The edge to remove does not exist.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occurred.

  • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

• error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

• code (integer): The response code.

• errorNum (integer): ArangoDB error number for the error that occurred.

• errorMessage (string): A message created for this error.

Examples

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/edge/relation/65672

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 41
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 202, 
  "removed" : true 
}

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/edge/relation/65672

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 41
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff