HTTP Interface for AQL User Functions Management

AQL User Functions Management

This is an introduction to ArangoDB's HTTP interface for managing AQL user functions. AQL user functions are a means to extend the functionality of ArangoDB's query language (AQL) with user-defined JavaScript code.

For an overview of how AQL user functions and their implications, please refer to the Extending AQL chapter.

The HTTP interface provides an API for adding, deleting, and listing previously registered AQL user functions.

All user functions managed through this interface will be stored in the system collection _aqlfunctions. Documents in this collection should not be accessed directly, but only via the dedicated interfaces.

Create AQL user function

create a new AQL user function

POST /_api/aqlfunction

A JSON object with these properties is required:

isDeterministic: an optional boolean value to indicate that the function results are fully deterministic (function return value solely depends on the input value and return value is the same for repeated calls with same input). The isDeterministic attribute is currently not used but may be used later for optimisations.
code: a string representation of the function body.
name: the fully qualified name of the user functions.

In case of success, the returned JSON object has the following properties:

error: boolean flag to indicate that an error occurred (false in this case)
code: the HTTP status code

The body of the response will contain a JSON object with additional error details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)
code: the HTTP status code
errorNum: the server error number
errorMessage: a descriptive error message

Example:

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
{ 
  "name" : "myfunctions::temperature::celsiustofahrenheit", 
  "code" : "function (celsius) { return celsius * 1.8 + 32; }" 
}
EOF

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

{ 
  "error" : false, 
  "code" : 201 
}

Return Codes

200: If the function already existed and was replaced by the call, the server will respond with HTTP 200.
201: If the function can be registered by the server, the server will respond with HTTP 201.
400: If the JSON representation is malformed or mandatory data is missing from the request, the server will respond with HTTP 400.

Examples

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
{ 
  "name" : "myfunctions::temperature::celsiustofahrenheit", 
  "code" : "function (celsius) { return celsius * 1.8 + 32; }" 
}
EOF

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

{ 
  "error" : false, 
  "code" : 201 
}

Remove existing AQL user function

remove an existing AQL user function

DELETE /_api/aqlfunction/{name}

Path Parameters

name (required): the name of the AQL user function.

Query Parameters

group (optional): If set to true, then the function name provided in name is treated as a namespace prefix, and all functions in the specified namespace will be deleted. If set to false, the function name provided in name must be fully qualified, including any namespaces.

Removes an existing AQL user function, identified by name.

In case of success, the returned JSON object has the following properties:

error: boolean flag to indicate that an error occurred (false in this case)
code: the HTTP status code

The body of the response will contain a JSON object with additional error details. The object has the following attributes:

error: boolean flag to indicate that an error occurred (true in this case)
code: the HTTP status code
errorNum: the server error number
errorMessage: a descriptive error message

Example:

deletes a function:

shell> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/square::x::y

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

{ 
  "error" : false, 
  "code" : 200 
}

Example:

function not found:

shell> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y

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

{ 
  "error" : true, 
  "code" : 404, 
  "errorNum" : 1582, 
  "errorMessage" : "user function '%s()' not found" 
}

Return Codes

200: If the function can be removed by the server, the server will respond with HTTP 200.
400: If the user function name is malformed, the server will respond with HTTP 400.
404: If the specified user user function does not exist, the server will respond with HTTP 404.

Examples

deletes a function:

shell> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/square::x::y

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

{ 
  "error" : false, 
  "code" : 200 
}

function not found:

shell> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y

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

{ 
  "error" : true, 
  "code" : 404, 
  "errorNum" : 1582, 
  "errorMessage" : "user function '%s()' not found" 
}

shell> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y

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

show response body

Return registered AQL user functions

gets all reqistered AQL user functions

GET /_api/aqlfunction

Query Parameters

namespace (optional): Returns all registered AQL user functions from namespace namespace.

Returns all registered AQL user functions.

The call will return a JSON array with all user functions found. Each user function will at least have the following attributes:

name: The fully qualified name of the user function
code: A string representation of the function body

Example:

shell> curl --dump - http://localhost:8529/_api/aqlfunction

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

[ 
  { 
    "name" : "myfunctions::temperature::celsiustofahrenheit", 
    "code" : "function (celsius) { return celsius * 1.8 + 32; }" 
  } 
]

Return Codes

200: if success HTTP 200 is returned.

Examples

shell> curl --dump - http://localhost:8529/_api/aqlfunction

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

[ 
  { 
    "name" : "myfunctions::temperature::celsiustofahrenheit", 
    "code" : "function (celsius) { return celsius * 1.8 + 32; }" 
  } 
]