A newer version of this documentation is available.

View Latest

Functions REST API

  • Developer Preview
    +

    This is a Developer Preview feature, intended for development purposes only. Do not use this feature in production. No Enterprise Support is provided for Developer Preview features.

    Refer to Developer Preview Mode for more information.

    Overview

    The Functions REST API is a secondary API provided by the Query service. This API enables you to manage the JavaScript libraries and objects that are used to create N1QL user-defined functions.

    The API schemes and host URLs are as follows:

    • http://node:8093/

    • https://node:18093/ (for secure access)

    where node is the host name or IP address of a computer running the N1QL query engine.

    Version information

    Version : 1.0

    Tags

    • collection : Operations for all libraries and functions.

    • libraries : Operations for individual libraries.

    • functions : Operations for individual functions.

    Consumes

    • application/json

    Produces

    • application/json

    Resources

    Table of Contents

    Collection

    Operations for all libraries and functions.

    Create or Update a Collection of Libraries

    POST /functions/v1/libraries
    Description

    Creates the specified libraries and their associated functions. If any specified library exists, the functions specified in the body for that library are appended to the existing library. If any specified function exists within an existing library, the existing function is overwritten.

    Parameters
    Type Name Description Schema

    Body

    Collection Definition
    required

    An array of objects, each of which gives information about one library.

    < Libraries > array

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    500

    Internal server error. The body of the request may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below creates or updates two libraries, math and science.

    Curl request
    $ curl -X POST \
      http://localhost:8093/functions/v1/libraries \
      -u Administrator:password \
      -H 'content-type: application/json' \
      -d '[ {
      "name" : "math",
      "functions" : [ {
        "name" : "adder",
        "code" : "function adder(a, b) { return a + b; }"
      }, {
        "name" : "multiplier",
        "code" : "function multiplier(a, b) { return a * b; }"
      } ]
    }, {
      "name" : "science",
      "functions" : [ {
        "name" : "f2c",
        "code" : "function f2c(f) { return (5/9)*(f-32); }"
      } ]
    } ]'

    Read All Libraries

    GET /functions/v1/libraries
    Description

    Returns all libraries and functions.

    Responses
    HTTP Code Description Schema

    200

    An array of objects, each of which gives information about one library.

    < Libraries > array

    Security
    Type Name

    basic

    Example HTTP request

    The example below fetches all defined libraries.

    Curl request
    $ curl -X GET \
      http://localhost:8093/functions/v1/libraries \
      -u Administrator:password
    Example HTTP response
    Response 200
    [ {
      "name" : "math",
      "functions" : [ {
        "name" : "adder",
        "id" : "d8:91:45:37:79:75:eb:15",
        "code" : "function adder(a, b) { return a + b; }"
      }, {
        "name" : "multiplier",
        "id" : "8e:ab:89:e6:1e:c2:21:1a",
        "code" : "function multiplier(a, b) { return a * b; }"
      } ]
    }, {
      "name" : "science",
      "functions" : [ {
        "name" : "f2c",
        "id" : "8c:7a:a3:f2:6c:4b:f8:ea",
        "code" : "function f2c(f) { return (5/9)*(f-32); }"
      } ]
    } ]

    Replace All Libraries

    PUT /functions/v1/libraries
    Description

    This has exactly the same effect as deleting all libraries followed by creating a collection of libraries. That is, all existing libraries in the system are deleted, and the libraries specified in the body of this call are created, resulting in the system having exclusively the libraries specified by this call.

    Parameters
    Type Name Description Schema

    Body

    Collection Definition
    required

    An array of objects, each of which gives information about one library.

    < Libraries > array

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    500

    Internal server error. The body of the request may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below removes all libraries in the system and creates two libraries, math and science.

    Curl request
    $ curl -X PUT \
      http://localhost:8093/functions/v1/libraries \
      -u Administrator:password \
      -H 'content-type: application/json' \
      -d '[ {
      "name" : "math",
      "functions" : [ {
        "name" : "adder",
        "code" : "function adder(a, b) { return a + b; }"
      }, {
        "name" : "multiplier",
        "code" : "function multiplier(a, b) { return a * b; }"
      } ]
    }, {
      "name" : "science",
      "functions" : [ {
        "name" : "f2c",
        "code" : "function f2c(f) { return (5/9)*(f-32); }"
      } ]
    } ]'

    Delete All Libraries

    DELETE /functions/v1/libraries
    Description

    Deletes all libraries entirely.

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below deletes all libraries defined in the system.

    Curl request
    $ curl -X DELETE \
      http://localhost:8093/functions/v1/libraries \
      -u Administrator:password

    Libraries

    Operations for individual libraries.

    Create or Update a Library

    POST /functions/v1/libraries/{library}
    Description

    Creates the specified library and its associated functions. If the specified library exists, the functions specified are added to the existing library. If a specified function exists within the existing library, the existing function is overwritten.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Body

    Library Definition
    required

    An object specifying a library.

    The name property in the library object must match the library name specified in the path.

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. The library name in the path might not match the name in the body of the request.

    No Content

    500

    Internal server error. The body of the request may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below creates or updates a library called math.

    Curl request
    $ curl -X POST \
      http://localhost:8093/functions/v1/libraries/math \
      -u Administrator:password \
      -H 'content-type: application/json' \
      -d '{
      "name" : "math",
      "functions" : [ {
        "name" : "add",
        "code" : "function add(a, b) { let data = a + b; return data; }"
      }, {
        "name" : "sub",
        "code" : "function sub(a, b) { let data = a - b; return data; }"
      }, {
        "name" : "mul",
        "code" : "function mul(a, b) { let data = a * b; return data; }"
      } ]
    }'

    Read a Library

    GET /functions/v1/libraries/{library}
    Description

    Returns a library with all its functions.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Responses
    HTTP Code Description Schema

    200

    An object giving information about the specified library.

    404

    Not found. The library name in the path may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below gets all functions in the library math.

    Curl request
    $ curl -X GET \
      http://localhost:8093/functions/v1/libraries/math \
      -u Administrator:password
    Example HTTP response
    Response 200
    {
      "name" : "math",
      "functions" : [ {
        "name" : "adder",
        "id" : "d8:91:45:37:79:75:eb:15",
        "code" : "function adder(a, b) { return a + b; }"
      }, {
        "name" : "multiplier",
        "id" : "8e:ab:89:e6:1e:c2:21:1a",
        "code" : "function multiplier(a, b) { return a * b; }"
      } ]
    }

    Replace a Library

    PUT /functions/v1/libraries/{library}
    Description

    This has exactly the same effect as deleting a library followed by creating a library. That is, if the library exists, it is deleted entirely and replaced with the contents of the library specified in the body of this call, resulting in the library having only functions specified by this call exclusively.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Body

    Library Definition
    required

    An object specifying a library.

    The name property in the library object must match the library name specified in the path.

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. The library name in the path might not match the name in the body of the request.

    No Content

    500

    Internal server error. The body of the request may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below replaces the math library with a new copy, dropping any old math library.

    Curl request
    $ curl -X PUT \
      http://localhost:8093/functions/v1/libraries/math \
      -u Administrator:password \
      -H 'content-type: application/json' \
      -d '{
      "name" : "math",
      "functions" : [ {
        "name" : "add",
        "code" : "function add(a, b) { let data = a + b; return data; }"
      }, {
        "name" : "sub",
        "code" : "function sub(a, b) { let data = a - b; return data; }"
      }, {
        "name" : "mul",
        "code" : "function mul(a, b) { let data = a * b; return data; }"
      } ]
    }'

    Delete a Library

    DELETE /functions/v1/libraries/{library}
    Description

    Deletes the specified library entirely.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    404

    Not found. The library name in the path may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below deletes the math library entirely.

    Curl request
    $ curl -X DELETE \
      http://localhost:8093/functions/v1/libraries/math \
      -u Administrator:password

    Functions

    Operations for individual functions.

    Create or Update a Function

    POST /functions/v1/libraries/{library}/functions/{function}
    Description

    Creates the specified function in the specified library. If the specified library does not exist, the library is created. If the function already exists in the specified library, the existing function is overwritten.

    Within the function object, the value of the name property must match the name of the JavaScript function that returns the result, as specified by the code property. If they do not match, you may get an evaluation error when you attempt to execute a N1QL user-defined function based on this code.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Path

    function
    required

    The name of a function.

    string

    Body

    Function Definition
    required

    An object specifying a function.

    The name property in the function object must match the function name specified in the path.

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. The function name in the path might not match the name in the body of the request.

    No Content

    500

    Internal server error. The body of the request may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below creates or updates a function called sub in the library called math. The JavaScript function sub matches the value of the name property.

    Curl request
    $ curl -X POST \
      http://localhost:8093/functions/v1/libraries/math/functions/sub \
      -u Administrator:password \
      -H 'content-type: application/json' \
      -d '{
      "name" : "sub",
      "code" : "function sub(a,b) { return helper(a,b); }
                function helper(a,b) { return a - b; }"
    }'

    Read a Function

    GET /functions/v1/libraries/{library}/functions/{function}
    Description

    Returns the specified function from the specified library.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Path

    function
    required

    The name of a function.

    string

    Responses
    HTTP Code Description Schema

    200

    An object giving information about the specified function.

    404

    Not found. The library name or function name in the path may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below gets the function f2c from the library science.

    Curl request
    $ curl -X GET \
      http://localhost:8093/functions/v1/libraries/science/functions/f2c \
      -u Administrator:password
    Example HTTP response
    Response 200
    {
      "name" : "f2c",
      "id" : "8c:7a:a3:f2:6c:4b:f8:ea",
      "code" : "function f2c(f) { return (5/9)*(f-32); }"
    }

    Replace a Function

    PUT /functions/v1/libraries/{library}/functions/{function}
    Description

    This has exactly the same effect as creating or updating a function, and is included for completeness.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Path

    function
    required

    The name of a function.

    string

    Body

    Function Definition
    required

    An object specifying a function.

    The name property in the function object must match the function name specified in the path.

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. The function name in the path might not match the name in the body of the request.

    No Content

    500

    Internal server error. The body of the request may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below creates or replaces a function called sub in the library called math.

    Curl request
    $ curl -X PUT \
      http://localhost:8093/functions/v1/libraries/math/functions/sub \
      -u Administrator:password \
      -H 'content-type: application/json' \
      -d '{
      "name" : "sub",
      "code" : "function sub(a,b) { return helper(a,b); }
                function helper(a,b) { return a - b; }"
    }'

    Delete a Function

    DELETE /functions/v1/libraries/{library}/functions/{function}
    Description

    Deletes the specified function in the specified library.

    Parameters
    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Path

    function
    required

    The name of a function.

    string

    Responses
    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    404

    Not found. The library name or function name in the path may be incorrect.

    No Content

    Security
    Type Name

    basic

    Example HTTP request

    The example below deletes the function sub in the math library.

    Curl request
    $ curl -X DELETE \
      http://localhost:8093/functions/v1/libraries/math/functions/sub \
      -u Administrator:password \
      -H 'content-type: application/json'

    Definitions

    Table of Contents

    Libraries

    Name Description Schema

    name
    required

    The name of the library.
    Example : "math"

    string

    functions
    required

    An array of objects, each of which gives information about one function.

    < Functions > array

    Functions

    Name Description Schema

    name
    required

    The name of the function. This must match the name of the JavaScript function that returns the result, as specified by the code property.
    Example : "f2c"

    string

    id
    optional

    A unique ID for the function. You do not need to specify an ID when creating or updating a function. An ID is generated automatically if you do not specify one.
    Example : "c4:1a:39:46:46:88:ff:3d"

    string

    code
    required

    The JavaScript code for the function. The name of the JavaScript function that returns the result must match the name specified by the name property. The JavaScript code may contain other helper functions.
    Example : "function f2c(f) { return (5/9)*(f-32); }"

    string

    Security

    Default

    The Functions API supports admin credentials. Credentials can be passed via HTTP headers (HTTP basic authentication).

    Type : basic