Handling Vertices

Examples will explain the REST API to the graph module on the social graph:

Create a vertex

create a new vertex

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

Path Parameters

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

• collection (string, required): The name of the vertex collection the vertex should be inserted into.

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

(object, required)

The body has to be the JSON object to be stored.

Adds a vertex to the given collection.

Responses

HTTP 201: Returned if the vertex could be added 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.

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

  • _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.

• new (object): The complete newly written vertex 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.

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.

• vertex (object): The internal attributes generated while storing the vertex. Does not include any attribute given in request body.

  • _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.

• new (object): The complete newly written vertex 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.

HTTP 403: Returned if your user has insufficient rights. In order to insert vertices 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 if no graph with this name could be found. Or if a graph is found but this 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.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/vertex/male <<EOF
{ 
  "name" : "Francis" 
}
EOF

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

{ 
  "error" : false, 
  "code" : 202, 
  "vertex" : { 
    "_id" : "male/65438", 
    "_key" : "65438", 
    "_rev" : "_eLYz9-m--F" 
  } 
}

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/vertex/male <<EOF
{ 
  "name" : "Francis" 
}
EOF

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

Get a vertex

fetches an existing vertex

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

Path Parameters

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

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

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

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 query parameter rev.

• 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 a vertex from the given collection.

Responses

HTTP 200: Returned if the vertex 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.

• vertex (object): The complete vertex.

  • _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.

HTTP 304: Returned if the if-none-match header is given and the currently stored vertex still has this revision value. So there was no update between the last time the vertex 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 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 --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/vertex/female/alice

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

{ 
  "error" : false, 
  "code" : 200, 
  "vertex" : { 
    "_key" : "alice", 
    "_id" : "female/alice", 
    "_rev" : "_eLYz9CW--_", 
    "name" : "Alice" 
  } 
}

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/vertex/female/alice

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

Update a vertex

update an existing vertex

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

Path Parameters

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

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

• vertex (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 delete 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 vertex in the collection.

Responses

HTTP 200: Returned if the vertex could be updated, 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.

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

  • _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.

• new (object): The complete newly written vertex 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.

• old (object): The complete overwritten vertex 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.

HTTP 202: Returned if the request was successful, 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.

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

  • _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.

• new (object): The complete newly written vertex 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.

• old (object): The complete overwritten vertex 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.

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. 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 vertex to update 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 PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/vertex/female/alice <<EOF
{ 
  "age" : 26 
}
EOF

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

{ 
  "error" : false, 
  "code" : 202, 
  "vertex" : { 
    "_id" : "female/alice", 
    "_key" : "alice", 
    "_oldRev" : "_eLYz9Ea---", 
    "_rev" : "_eLYz9Ee---" 
  } 
}

shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/vertex/female/alice <<EOF
{ 
  "age" : 26 
}
EOF

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

Replace a vertex

replaces an existing vertex

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

Path Parameters

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

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

• vertex (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

(object, required)

The body has to be the JSON object to be stored.

Replaces the data of a vertex in the collection.

Responses

HTTP 200: Returned if the vertex could be replaced, 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.

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

  • _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.

• new (object): The complete newly written vertex 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.

• old (object): The complete overwritten vertex 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.

HTTP 202: Returned if the vertex could be replaced, 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.

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

  • _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.

• new (object): The complete newly written vertex 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.

• old (object): The complete overwritten vertex 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.

HTTP 403: Returned if your user has insufficient rights. In order to replace 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 vertex to replace 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/vertex/female/alice <<EOF
{ 
  "name" : "Alice Cooper", 
  "age" : 26 
}
EOF

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

{ 
  "error" : false, 
  "code" : 202, 
  "vertex" : { 
    "_id" : "female/alice", 
    "_key" : "alice", 
    "_oldRev" : "_eLYz9Gy--_", 
    "_rev" : "_eLYz9G2--D" 
  } 
}

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/vertex/female/alice <<EOF
{ 
  "name" : "Alice Cooper", 
  "age" : 26 
}
EOF

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

Remove a vertex

removes a vertex from a graph

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

Path Parameters

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

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

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

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 a vertex from the collection.

Responses

HTTP 200: Returned if the vertex 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 vertex 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.

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 vertex 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.

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 vertex 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/vertex/female/alice

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/vertex/female/alice

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