You are viewing the documentation for a prerelease version.

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

Consumes

  • application/json

Produces

  • application/json

Paths

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

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

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

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