{
"basePath": "/",
"swaggerVersion": "1.1",
"apiVersion": "0.1",
"apis": [
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the edge was created successfully and waitForSync was true.
",
"code": "201"
},
{
"reason": "is returned if the edge was created successfully and waitForSync was false.
",
"code": "202"
},
{
"reason": "is returned if the body does not contain a valid JSON representation of an edge, or if the collection specified is not an edge collection. The response body contains an error document in this case.
",
"code": "400"
},
{
"reason": "is returned if the collection specified by collection is unknown. The response body contains an error document in this case.
",
"code": "404"
}
],
"parameters": [
{
"dataType": "Json",
"paramType": "body",
"required": true,
"name": "edge-document",
"description": "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.
"
},
{
"dataType": "String",
"paramType": "query",
"required": true,
"name": "collection",
"description": "Creates a new edge in the collection identified by collection name.
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "createCollection",
"description": "If this parameter has a value of true or yes, then the collection is created if it does not yet exist. Other values will be ignored so the collection must be present for the operation to succeed.
Note: This flag is not supported in a cluster. Using it will result in an error.
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "waitForSync",
"description": "Wait until the edge document has been synced to disk.
"
},
{
"dataType": "String",
"paramType": "query",
"required": true,
"name": "from",
"description": "The document handle of the start point must be passed in from handle.
"
},
{
"dataType": "String",
"paramType": "query",
"required": true,
"name": "to",
"description": "The document handle of the end point must be passed in to handle.
"
}
],
"notes": "Creates a new edge document in the collection named collection. A JSON representation of the document must be passed as the body of the POST request.
The from and to handles are immutable once the edge has been created.
In all other respects the method works like POST /document.
",
"summary": "Create edge",
"httpMethod": "POST",
"examples": "
Create an edge and read it back:
shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/edge/?collection=edges&from=vertices/1&to=vertices/2 <<EOF\n{ \n \"name\" : \"Emil\" \n}\nEOF\n\nHTTP/1.1 202 Accepted\ncontent-type: application/json; charset=utf-8\netag: \"1641882677\"\nlocation: /_db/_system/_api/document/edges/1641882677\n\n{ \n \"error\" : false, \n \"_id\" : \"edges/1641882677\", \n \"_rev\" : \"1641882677\", \n \"_key\" : \"1641882677\" \n}\nshell> curl --dump - http://localhost:8529/_api/edge/edges/1641882677\n\nHTTP/1.1 200 OK\ncontent-type: application/json; charset=utf-8\netag: \"1641882677\"\n\n{ \n \"name\" : \"Emil\", \n \"_id\" : \"edges/1641882677\", \n \"_rev\" : \"1641882677\", \n \"_key\" : \"1641882677\", \n \"_from\" : \"vertices/1\", \n \"_to\" : \"vertices/2\" \n}\n
",
"nickname": "CreateEdge"
}
],
"path": "/_api/edge"
},
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the edge was found
",
"code": "200"
},
{
"reason": "is returned if the \"If-None-Match\" header is given and the edge has the same version
",
"code": "304"
},
{
"reason": "is returned if the edge or collection was not found
",
"code": "404"
},
{
"reason": "is returned if a \"If-Match\" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.
",
"code": "412"
}
],
"parameters": [
{
"dataType": "String",
"paramType": "path",
"required": true,
"name": "document-handle",
"description": "The handle of the edge document.
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-None-Match",
"description": "If the \"If-None-Match\" header is given, then it must contain exactly one etag. The edge is returned if it has a different revision than the given etag. Otherwise an HTTP 304 is returned.
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-Match",
"description": "If the \"If-Match\" header is given, then it must contain exactly one etag. The edge is returned if it has the same revision ad the given etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the etag in an attribute rev in the URL.
"
}
],
"notes": "Returns the edge identified by document-handle. The returned edge contains a few special attributes:
- _id contains the document handle
- _rev contains the revision
- _from and to contain the document handles of the connected vertex documents",
"summary": " Read edge",
"httpMethod": "GET",
"examples": "",
"nickname": "ReadEdge"
}
],
"path": "/_api/edge/{document-handle}"
},
{
"operations": [
{
"errorResponses": [
{
"reason": "All went good.
",
"code": "200"
},
{
"reason": "The collection does not exist.
",
"code": "404"
}
],
"parameters": [
{
"dataType": "String",
"paramType": "query",
"required": true,
"name": "collection",
"description": "The name of the collection.
"
}
],
"notes": "Returns an array of all URIs for all edges from the collection identified by collection.
",
"summary": " Read all edges from collection",
"httpMethod": "GET",
"examples": "",
"nickname": "ReadAllEdgesFromCollection"
}
],
"path": "/_api/edge"
},
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the edge document was found
",
"code": "200"
},
{
"reason": "is returned if the \"If-None-Match\" header is given and the edge document has same version
",
"code": "304"
},
{
"reason": "is returned if the edge document or collection was not found
",
"code": "404"
},
{
"reason": "is returned if a \"If-Match\" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the etag header.
",
"code": "412"
}
],
"parameters": [
{
"dataType": "String",
"paramType": "path",
"required": true,
"name": "document-handle",
"description": "The handle of the edge document.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "rev",
"description": "You can conditionally fetch an edge document based on a target revision id by using the rev URL parameter.
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-None-Match",
"description": "If the \"If-None-Match\" header is given, then it must contain exactly one etag. If the current document revision is different to the specified etag, an HTTP 200 response is returned. If the current document revision is identical to the specified etag, then an HTTP 304 is returned.
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-Match",
"description": "You can conditionally fetch an edge document based on a target revision id by using the if-match HTTP header.
"
}
],
"notes": "Like GET, but only returns the header fields and not the body. You can use this call to get the current revision of an edge document or check if it was deleted.
",
"summary": " Read edge header",
"httpMethod": "HEAD",
"examples": "",
"nickname": "ReadEdgeHeader"
}
],
"path": "/_api/edge/{document-handle}"
},
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the edge document was replaced successfully and waitForSync was true.
",
"code": "201"
},
{
"reason": "is returned if the edge document was replaced successfully and waitForSync was false.
",
"code": "202"
},
{
"reason": "is returned if the body does not contain a valid JSON representation of an edge document or if applied to a non-edge collection. The response body contains an error document in this case.
",
"code": "400"
},
{
"reason": "is returned if the collection or the edge document was not found
",
"code": "404"
},
{
"reason": "is returned if a \"If-Match\" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.
",
"code": "412"
}
],
"parameters": [
{
"dataType": "Json",
"paramType": "body",
"required": true,
"name": "edge",
"description": "A JSON representation of the new edge data.
"
},
{
"dataType": "String",
"paramType": "path",
"required": true,
"name": "document-handle",
"description": "The handle of the edge document.
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "waitForSync",
"description": "Wait until edge document has been synced to disk.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "rev",
"description": "You can conditionally replace an edge document based on a target revision id by using the rev URL parameter.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "policy",
"description": "To control the update behavior in case there is a revision mismatch, you can use the policy parameter (see below).
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-Match",
"description": "You can conditionally replace an edge document based on a target revision id by using the if-match HTTP header.
"
}
],
"notes": "Completely updates (i.e. replaces) the edge document identified by document-handle. If the edge document exists and can be updated, then a HTTP 201 is returned and the \"ETag\" header field contains the new revision of the edge document.
If the new edge document passed in the body of the request contains the document-handle in the attribute _id and the revision in _rev, these attributes will be ignored. Only the URI and the \"ETag\" header are relevant in order to avoid confusion when using proxies. Note: The attributes _from and _to of an edge are immutable and cannot be updated either.
Optionally, the URL parameter waitForSync can be used to force synchronisation of the edge document replacement operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL parameter can be used to force synchronisation of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync URL parameter cannot be used to disable synchronisation for collections that have a default waitForSync value of true.
The body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the updated edge document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision.
If the edge document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.
There are two ways for specifying the targeted revision id for conditional replacements (i.e. replacements that will only be executed if the revision id found in the database matches the revision id specified in the request): - specifying the target revision in the rev URL query parameter
- specifying the target revision in the if-match HTTP header
Specifying a target revision is optional, however, if done, only one of the described mechanisms must be used (either the rev URL parameter or the if-match HTTP header). Regardless which mechanism is used, the parameter needs to contain the target revision id as returned in the _rev attribute of an edge document or by an HTTP etag header.
For example, to conditionally replace an edge document based on a specific revision id, you can use the following request:
- PUT /_api/document/document-handle?rev=etag
If a target revision id is provided in the request (e.g. via the etag value in the rev URL query parameter above), ArangoDB will check that the revision id of the edge document found in the database is equal to the target revision id provided in the request. If there is a mismatch between the revision id, then by default a HTTP 412 conflict is returned and no replacement is performed.
The conditional update behavior can be overriden with the policy URL query parameter:
- PUT /_api/document/document-handle?policy=policy
If policy is set to error, then the behavior is as before: replacements will fail if the revision id found in the database does not match the target revision id specified in the request.
If policy is set to last, then the replacement will succeed, even if the revision id found in the database does not match the target revision id specified in the request. You can use the last *policy* to force replacements.
",
"summary": "replaces an edge",
"httpMethod": "PUT",
"examples": "",
"nickname": "replacesAnEdge"
}
],
"path": "/_api/edge/{document-handle}"
},
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the document was patched successfully and waitForSync was true.
",
"code": "201"
},
{
"reason": "is returned if the document was patched successfully and waitForSync was false.
",
"code": "202"
},
{
"reason": "is returned if the body does not contain a valid JSON representation or when applied on an non-edge collection. The response body contains an error document in this case.
",
"code": "400"
},
{
"reason": "is returned if the collection or the edge document was not found
",
"code": "404"
},
{
"reason": "is returned if a \"If-Match\" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.
",
"code": "412"
}
],
"parameters": [
{
"dataType": "Json",
"paramType": "body",
"required": true,
"name": "document",
"description": "A JSON representation of the edge update.
"
},
{
"dataType": "String",
"paramType": "path",
"required": true,
"name": "document-handle",
"description": "The handle of the edge document.
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "keepNull",
"description": "If the intention is to delete existing attributes with the patch command, the URL query parameter keepNull can be used with a value of false. This will modify the behavior of the patch command to remove any attributes from the existing edge document that are contained in the patch document with an attribute value of null.
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "mergeObjects",
"description": "Controls whether objects (not arrays) will be merged if present in both the existing and the patch edge. If set to false, the value in the patch edge will overwrite the existing edge's value. If set to true, objects will be merged. The default is true.
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "waitForSync",
"description": "Wait until edge document has been synced to disk.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "rev",
"description": "You can conditionally patch an edge document based on a target revision id by using the rev URL parameter.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "policy",
"description": "To control the update behavior in case there is a revision mismatch, you can use the policy parameter.
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-Match",
"description": "You can conditionally patch an edge document based on a target revision id by using the if-match HTTP header.
"
}
],
"notes": "Partially updates the edge document identified by document-handle. The body of the request must contain a JSON document with the attributes to patch (the patch document). All attributes from the patch document will be added to the existing edge document if they do not yet exist, and overwritten in the existing edge document if they do exist there.
Setting an attribute value to null in the patch document will cause a value of null be saved for the attribute by default.
Note: Internal attributes such as _key, _from and _to are immutable once set and cannot be updated.
Optionally, the URL parameter waitForSync can be used to force synchronisation of the edge document update operation to disk even in case that the waitForSync flag had been disabled for the entire collection. Thus, the waitForSync URL parameter can be used to force synchronisation of just specific operations. To use this, set the waitForSync parameter to true. If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync URL parameter cannot be used to disable synchronisation for collections that have a default waitForSync value of true.
The body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the updated edge document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision.
If the edge document does not exist, then a HTTP 404 is returned and the body of the response contains an error document.
You can conditionally update an edge document based on a target revision id by using either the rev URL parameter or the if-match HTTP header. To control the update behavior in case there is a revision mismatch, you can use the policy parameter. This is the same as when replacing edge documents (see replacing documents for details).
",
"summary": " Patches edge",
"httpMethod": "PATCH",
"examples": "",
"nickname": "PatchesEdge"
}
],
"path": "/_api/edge/{document-handle}"
},
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the edge document was deleted successfully and waitForSync was true.
",
"code": "200"
},
{
"reason": "is returned if the edge document was deleted successfully and waitForSync was false.
",
"code": "202"
},
{
"reason": "is returned if the collection or the edge document was not found. The response body contains an error document in this case.
",
"code": "404"
},
{
"reason": "is returned if a \"If-Match\" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned.
",
"code": "412"
}
],
"parameters": [
{
"dataType": "String",
"paramType": "path",
"required": true,
"name": "document-handle",
"description": "Deletes the edge document identified by document-handle.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "rev",
"description": "You can conditionally delete an edge document based on a target revision id by using the rev URL parameter.
"
},
{
"dataType": "String",
"paramType": "query",
"required": false,
"name": "policy",
"description": "To control the update behavior in case there is a revision mismatch, you can use the policy parameter. This is the same as when replacing edge documents (see replacing edge documents for more details).
"
},
{
"dataType": "Boolean",
"paramType": "query",
"required": false,
"name": "waitForSync",
"description": "Wait until edge document has been synced to disk.
"
},
{
"dataType": "String",
"paramType": "header",
"name": "If-Match",
"description": "You can conditionally delete an edge document based on a target revision id by using the if-match HTTP header.
"
}
],
"notes": "The body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the deleted edge document, _key contains the key which uniquely identifies a document in a given collection, and the attribute _rev contains the new document revision.
If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync URL parameter cannot be used to disable synchronisation for collections that have a default waitForSync value of true.
",
"summary": " Deletes edge",
"httpMethod": "DELETE",
"examples": "",
"nickname": "DeletesEdge"
}
],
"path": "/_api/edge/{document-handle}"
}
]
}