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