A newer version of this documentation is available.

View Latest

Functions REST API

    January 12, 2025
    + 12

    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

    Consumes

    • application/json

    Produces

    • application/json

    Paths

    Table of Contents

    Read All Libraries

    GET /evaluator/v1/libraries/

    Description

    Returns all libraries and functions.

    Responses

    HTTP Code Description Schema

    200

    An object with multiple properties, each giving information about a single library.

    404

    Not found. The path may be missing its trailing slash.

    No Content

    406

    Not acceptable. The path may not conform to the schema.

    string

    Security

    Type Name

    basic

    Example HTTP request

    Request 1: Fetch all defined libraries.

    Curl request
    shell
    curl -X GET \ http://localhost:8093/evaluator/v1/libraries/ \ -u Administrator:password

    Example HTTP response

    Response 200
    json
    { "math": "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }", "science": "function f2c(f) { return (5/9)*(f-32); }" }

    Read a Library

    GET /evaluator/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 with a single property, giving information about the specified library.

    404

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

    string

    406

    Not acceptable. The path may not conform to the schema.

    string

    Security

    Type Name

    basic

    Example HTTP request

    Request 2: Get all functions in the library math.

    Curl request
    shell
    curl -X GET \ http://localhost:8093/evaluator/v1/libraries/math \ -u Administrator:password

    Example HTTP response

    Response 200
    json
    { "math": "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }" }

    Create or Update a Library

    POST /evaluator/v1/libraries/{library}

    Description

    Creates the specified library and its associated functions. If the specified library exists, the existing library is overwritten.

    • To add a function to a library, update the library with all existing functions, plus the new function.

    • To update a function, update the library with all existing functions, including the updated function definition.

    • To delete a function from a library, update the library with all existing functions, without the deleted function.

    Parameters

    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Body

    functions
    required

    The JavaScript code for all functions in the library.

    string

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    string

    400

    Bad request. The body of the request may be incorrect.

    string

    406

    Not acceptable. The path may not conform to the schema.

    string

    Security

    Type Name

    basic

    Example HTTP request

    Request 3: Create or update a library called math. The library contains two functions, add and sub.

    Curl request
    shell
    curl -X POST \ http://localhost:8093/evaluator/v1/libraries/math \ -u Administrator:password \ -H 'content-type: application/json' \ -d 'function add(a, b) { let data = a + b; return data; } function sub(a, b) { let data = a - b; return data; }'

    Request 4: Add a function called mul to the library, leaving the other functions unchanged.

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

    Request 5: Edit the function called sub to use a helper function called helper, leaving the other functions unchanged.

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

    Request 6: Remove the function called sub and the helper function called helper, leaving the other functions unchanged.

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

    Delete a Library

    DELETE /evaluator/v1/libraries/{library}

    Description

    Deletes the specified library entirely.

    Before you can delete a library, you must first drop all N1QL external user-defined functions which point to any of the JavaScript functions within that library. For further details, refer to DROP FUNCTION.

    Parameters

    Type Name Description Schema

    Path

    library
    required

    The name of a library.

    string

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    string

    404

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

    string

    406

    Not acceptable. The path may not conform to the schema.

    string

    Security

    Type Name

    basic

    Example HTTP request

    Request 7: Delete the math library entirely.

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

    Definitions

    Libraries

    Name Description Schema

    library
    required

    The JavaScript code for all functions in the library.

    The name of the property is the name of the library.
    Example : "function add(a, b) { return a + b; } function mul(a, b) { return a * b; }"

    string

    Security

    Default

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

    Type : basic