Handling Vertices

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

Social Example Graph

Create a vertex

create a new vertex

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

Adds a vertex to the given collection.

HTTP 201 A json document with these Properties is returned:

Returned if the vertex could be added and waitForSync is true.

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 202 A json document with these Properties is returned:

Returned if the request was successful but waitForSync is false.

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 403 A json document with these Properties is returned:

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.
  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 404 A json document with these Properties is returned:

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.

  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Path Parameters

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

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

Query Parameters

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

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

Request Body (required)

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

Return Codes

  • 201: Returned if the vertex could be added and waitForSync is true.

Response Body

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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 Accepted
content-type: application/json; charset=utf-8
etag: _YDCrS9C--F
x-content-type-options: nosniff

Show response body

Get a vertex

fetches an existing vertex

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

Gets a vertex from the given collection.

HTTP 200 A json document with these Properties is returned:

Returned if the vertex could be found.

  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 304 A json document with these Properties is returned:

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.

  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 403 A json document with these Properties is returned:

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.
  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 404 A json document with these Properties is returned:

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.

  • errorMessage: A message created for this error.

  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 412 A json document with these Properties is returned:

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

  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Path Parameters

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

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

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

Query Parameters

  • rev (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 (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 (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.

Return Codes

  • 200: Returned if the vertex could be found.

Response Body

  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Examples

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
etag: _YDCrTd6--_
x-content-type-options: nosniff

Show response body

Update a vertex

update an existing vertex

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

Updates the data of the specific vertex in the collection.

HTTP 200 A json document with these Properties is returned:

Returned if the vertex could be updated, and waitForSync is true.

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 202 A json document with these Properties is returned:

Returned if the request was successful, and waitForSync is false.

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 403 A json document with these Properties is returned:

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.
  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 404 A json document with these Properties is returned:

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.

  • errorMessage: A message created for this error.

  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 412 A json document with these Properties is returned:

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

  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Path Parameters

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

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

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

Query Parameters

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

  • keepNull (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 (optional): Define if a presentation of the deleted document should be returned within the response object.

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

Header Parameters

  • if-match (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 (required)

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

Return Codes

  • 200: Returned if the vertex could be updated, and waitForSync is true.

Response Body

  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

  • 202: Returned if the request was successful, and waitForSync is false.

Response Body

  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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 Accepted
content-type: application/json; charset=utf-8
etag: _YDCrTxu--F
x-content-type-options: nosniff

Show response body

Replace a vertex

replaces an existing vertex

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

Replaces the data of a vertex in the collection.

HTTP 200 A json document with these Properties is returned:

Returned if the vertex could be replaced, and waitForSync is true.

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 202 A json document with these Properties is returned:

Returned if the vertex could be replaced, and waitForSync is false.

  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 403 A json document with these Properties is returned:

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.
  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 404 A json document with these Properties is returned:

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.

  • errorMessage: A message created for this error.

  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 412 A json document with these Properties is returned:

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

  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Path Parameters

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

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

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

Query Parameters

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

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

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

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

Header Parameters

  • if-match (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 (required)

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

Return Codes

  • 200: Returned if the vertex could be replaced, and waitForSync is true.

Response Body

  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

  • 202: Returned if the vertex could be replaced, and waitForSync is false.

Response Body

  • vertex:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • new:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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 Accepted
content-type: application/json; charset=utf-8
etag: _YDCrUGi--D
x-content-type-options: nosniff

Show response body

Remove a vertex

removes a vertex from a graph

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

Removes a vertex from the collection.

HTTP 200 A json document with these Properties is returned:

Returned if the vertex could be removed.

  • removed: Is set to true if the remove was successful.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 202 A json document with these Properties is returned:

Returned if the request was successful but waitForSync is false.

  • removed: Is set to true if the remove was successful.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

HTTP 403 A json document with these Properties is returned:

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.
  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 404 A json document with these Properties is returned:

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.

  • errorMessage: A message created for this error.

  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

HTTP 412 A json document with these Properties is returned:

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

  • errorMessage: A message created for this error.
  • errorNum: ArangoDB error number for the error that occured.
  • code: The response code.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Path Parameters

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

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

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

Query Parameters

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

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

Header Parameters

  • if-match (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.

Return Codes

  • 200: Returned if the vertex could be removed.

Response Body

  • removed: Is set to true if the remove was successful.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • removed: Is set to true if the remove was successful.
  • code: The response code.
  • old:
    • _key: The _key value of the stored data.
    • _rev: The _rev value of the stored data.
    • _id: The _id value of the stored data.
  • error: Flag if there was an error (true) or not (false). It is false in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

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

Response Body

  • errorMessage: A message created for this error.
  • code: The response code.
  • errorNum: ArangoDB error number for the error that occured.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

Examples

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

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body