arangodb/Documentation/Books/Users/HttpAqlUserFunctions

!CHAPTER HTTP Interface for AQL User Functions Management

!SUBSECTION 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 work, please refer to
[Extending Aql](../AqlExtending/README.md).

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.

`POST /_api/aqlfunction`*(creates or replaces an AQL user function)*

!SUBSECTION Body parameters

`body (json,required)`

the body with name and code of the aql user function.

!SUBSECTION Description

The following data need to be passed in a JSON representation in the body of the POST request:

* name: the fully qualified name of the user functions.
* code: a string representation of the function body.
* 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.

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

!SUBSECTION Return codes

`HTTP 200`

If the function already existed and was replaced by the call, the server will respond with HTTP 200.

`HTTP 201`

If the function can be registered by the server, the server will respond with HTTP 201.

`HTTP 400`

If the JSON representation is malformed or mandatory data is missing from the request, the server will respond with HTTP 400.
Examples

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

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

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

`DELETE /_api/aqlfunction/{name}`*(remove an existing AQL user function)*

!SUBSECTION URL parameters

`name (string,required)`

the name of the AQL user function.


!SUBSECTION Query parameters

`group (string,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.

!SUBSECTION Description

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

!SUBSECTION Return codes

`HTTP 200`

If the function can be removed by the server, the server will respond with HTTP 200.

`HTTP 400`

If the user function name is malformed, the server will respond with HTTP 400.

`HTTP 404`

If the specified user user function does not exist, the server will respond with HTTP 404.

*Examples*

Deletes a function:

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

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

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

function not found:

unix> 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

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

`GET /_api/aqlfunction`*(returns registered AQL user functions)*

!SUBSECTION Query parameters

`namespace (string,optional)`

Returns all registered AQL user functions from namespace namespace.

!SUBSECTION Description

Returns all registered AQL user functions.
The call will return a JSON list 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

!SUBSECTION Return codes

`HTTP 200`

if success HTTP 200 is returned.

*Examples*

```
unix> curl --dump - http://localhost:8529/_api/aqlfunction

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

[ ]
```




<!--
@anchor HttpAqlFunctionsSave
@copydetails JSF_post_api_aqlfunction

@CLEARPAGE
@anchor HttpAqlFunctionsRemove
@copydetails JSF_delete_api_aqlfunction

@CLEARPAGE
@anchor HttpAqlFunctionsList
@copydetails JSF_get_api_aqlfunction
-->