A newer version of this documentation is available.

View Latest

Eventing REST API

    +
    The Eventing REST API, available by default at port 8096, provides the methods available to work with Couchbase Eventing Functions.
    The Eventing Functions REST API endpoints on this page are supported, as long as the content of the handler body is not created or modified externally (as the internal format of the body is not yet standardized).
    Table 1. Eventing Functions API (basic activation/deactivation)
    HTTP Method URI Path Description

    POST

    /api/v1/functions/[sample_name]/deploy

    Deploys an undeployed Function. Starting with version 6.5.0, this is the preferred invocation. A deploy CURL example is provided for reference.

    Sample API:

    curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/deploy

    POST

    /api/v1/functions/[sample_name]/undeploy

    Undeploys a Function. Starting with version 6.5.0, this is the preferred invocation. An undeploy CURL example is provided for reference.

    Sample API:

    curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/undeploy

    POST

    /api/v1/functions/[sample_name]/pause

    Pauses a Function and creates a DCP checkpoint such that on a subsequent resume no mutations will be lost. Starting with version 6.5.0, this is the preferred invocation. A pause CURL example is provided for reference.

    Sample API:

    curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/pause

    POST

    /api/v1/functions/[sample_name]/resume

    Resumes a paused function from its paused DCP checkpoint. Starting with version 6.5.0, this is the preferred invocation. A resume CURL example is provided for reference.

    Sample API:

    curl -XPOST http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/resume
    Table 2. Eventing Functions API (advanced)
    HTTP Method URI Path Description

    POST

    /api/v1/functions/[function_name]

    Import or create a single Function. The Function name in the body must match that on the URL. Function definition includes current settings. The POST data or POST data file must be a single JSON object or an array containing a single JSON object

    Sample API (from file):

    curl -XPOST  -d @./[sample_name].json http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]

    POST

    /api/v1/functions/

    Imports or creates multiple Functions. Function names must be unique. When multiple Functions have the same name, an error is reported. The POST data or POST data file must be either a single JSON object or an array containing a one or more JSON objects

    Sample API (from file):

    curl -XPOST  -d @./[array_of_functions].json http://Administrator:password@192.168.1.5:8096/api/v1/functions

    POST

    /api/v1/import/

    Imports multiple Functions. Function names must be unique. When multiple Functions have the same name, an error is reported. The POST data or POST data file must be either a single JSON object or an array containing a one or more JSON objects Note if any Function’s language_compatibility field is missing the value will be set to 6.0.0 (unlike the /api/v1/functions above which will set the value to the highest version supported by the server).

    Sample API (from file):

    curl -XPOST  -d @./[array_of_functions].json http://Administrator:password@192.168.1.5:8096/api/v1/import

    GET

    /api/v1/functions/[sample_name]

    View a definition of a Function. Provides a listing of a complete Function definition available in the cluster. The Function could be in any state: deployed, undeployed, or paused. If saved to a file the function definition can be imputed into the cluster or a different cluster. However any changes to the function definition made to the file outside the UI are discouraged and not supported.

    Sample API (to standard out):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]

    Sample API (to file):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name] -o [sample_name].json

    GET

    /api/v1/functions

    View definitions of all Functions. Provides an array of definitions of all Functions available in the cluster. The Functions could be in any state: deployed, undeployed, or paused. If saved to a file the function definitions can be imputed into the cluster or a different cluster. However, any changes to the function definition made to the file outside the UI are discouraged and not supported.

    Sample API (to standard out):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions

    Sample API (to file):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions -o array_of_functions.json

    DELETE

    /api/v1/functions/[function_name]

    Deletes a specific Function from the cluster. WARNING: Use this API with caution as it is irreversible.

    Sample API:

    curl -XDELETE http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]

    DELETE

    /api/v1/functions

    Deletes multiple Functions from the cluster. WARNING: Use this API with caution as it is irreversible.

    Sample API:

    curl -XDELETE http://Administrator:password@192.168.1.5:8096/api/v1/functions

    GET

    /api/v1/config

    List global configuration. The response shows all global Eventing settings.

    Sample API:

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/config

    POST

    /api/v1/config

    Modify global configuration. During an edit, settings provided are merged. Unspecified attributes retain their prior values. The response indicates whether the Eventing service must be restarted for the new changes to take effect.

    Sample API (alter ram_quota):

    curl -XPOST -d '{"ram_quota": 512}' http://Administrator:password@192.168.1.5:8096/api/v1/config

    GET

    /api/v1/functions/[function_name]/settings

    Export or return the full definition for one Eventing Function in the cluster. The definition can be subsequently imported. However any changes to the function definition made to the file outside the UI are discouraged and not supported.

    Sample API (to standard out):

    curl http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings

    Sample API (to file):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings -o [sample_name].json

    POST

    /api/v1/functions/[function_name]/settings

    Updates an undeployed Function with the provided setting. Do not update settings for a deployed or paused function. During an edit, settings provided are merged. Unspecified attributes retain their prior values. Note that you must always specify deployment_status (deployed/undeployed) and processing_status (paused/not-paused) when using this REST endpoint to update any option or set of options.

    Sample API (alter worker_count):

    curl -XPOST -d '{"deployment_status":false,"processing_status":false,"worker_count":6}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings

    Sample API (alter app_log_max_files and app_log_max_size):

    curl -XPOST -d '{"deployment_status":false,"processing_status":false,"app_log_max_files":5,"app_log_max_size":10485760}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings

    Sample API (alter timer_context_size):

    curl -XPOST -d '{"deployment_status":false,"processing_status":false,"timer_context_size":2048}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings

    GET

    /api/v1/status

    Returns a list (arrary) of all Eventing Functions showing their corresponding composite_status. It can have one of the following values - undeployed, deploying, deployed, undeploying, paused, and 'pausing. Note, there is no value of resuming when resuming a paused Eventing Function the composite_status will return deploying until it reaches the deployed state.

    Sample API (status):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/status
    Table 3. Eventing Functions API (deprecated activation/deactivation)
    HTTP Method URI Path Description

    POST

    /api/v1/functions/[function_name]/settings

    Deploys an undeployed Function or resumes a paused function from its paused DCP checkpoint. Deprecated, see (basic activation/deactivation) for preferred invocation. A deploy/resume CURL example is provided for reference.

    Sample API:

    curl -XPOST -d '{"deployment_status":true,"processing_status":true}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings

    POST

    /api/v1/functions/[function_name]/settings

    Undeploys a Function. Deprecated, see (basic activation/deactivation) for preferred invocation. An undeploy CURL example is provided for reference.

    Sample API:

    curl -XPOST -d '{"deployment_status":false,"processing_status":false}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings

    POST

    /api/v1/functions/[function_name]/settings

    Pauses a Function and creates a DCP checkpoint such that on a subsequent resume no mutations will be lost. Deprecated, see (basic activation/deactivation) for preferred invocation. A pause CURL example is provided for reference.

    Sample API:

    curl -XPOST -d '{"deployment_status":true,"processing_status":false}' http://Administrator:password@192.168.1.5:8096/api/v1/functions/[sample_name]/settings
    Table 4. Eventing Statistics API
    HTTP Method URI Path Description

    GET

    /api/v1/stats?type=full

    Retrieve all statistics for the node. This will return the full statistics set inclusive of events processing, events remaining, execution, failure, latency, worker PIDs and sequence processed.

    Omitting the parameter type=full will exclude dcp_event_backlog_per_vb, doc_timer_debug_stats, latency_stats, plasma_stats, and seqs_processed from the response.

    Sample API (basic):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/stats

    Sample API (full):

    curl -XGET http://Administrator:password@192.168.1.5:8096/api/v1/stats?type=full

    GET

    /getExecutionStats?name=[function_name]

    Retrieve only execution statistics. This will return the subset of statistics for the node.

    Sample API:

    curl -XGET http://Administrator:password@192.168.1.5:8096/getExecutionStats?name=[function_name]

    GET

    /getLatencyStats?name=[function_name]

    Retrieve only latency statistics. This will return the subset of statistics for the node.

    Sample API:

    curl -XGET http://Administrator:password@192.168.1.5:8096/getLatencyStats?name=[function_name]

    GET

    /getFailureStats?name=[function_name]

    Retrieve only failure statistics. This will return the subset of statistics for the node.

    Sample API:

    curl -XGET http://Administrator:password@192.168.1.5:8096/getFailureStats?name=[function_name]