A newer version of this documentation is available.

View Latest

Functions REST API

      +

      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
      curl -X GET \
      http://localhost:8093/evaluator/v1/libraries/ \
      -u Administrator:password

      Example HTTP response

      Response 200
      {
        "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
      curl -X GET \
      http://localhost:8093/evaluator/v1/libraries/math \
      -u Administrator:password

      Example HTTP response

      Response 200
      {
        "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
      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
      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
      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
      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
      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