Invoke a Function

If your Function is Running, it's ready to be invoked. Invoking a Function consists in making a request to one of the two invocation endpoints:
  1. /spaces/<space>/functions/<function_name</invoke will invoke your function synchronously, so the response to that request will be the output of the function.
  2. /spaces/<space>/functions/<function_name</async-invoke will invoke your function asynchronously, which is best suited for long-running tasks. That means your function will run and send the response as a request to the URL you choose.

Synchronous Invocation

When you invoke a function synchronously, you're waiting for it to complete its task before moving on to the next step in your workflow. This ensures that the function's outcome is immediately available for further processing.

When a synchronous invocation is made, a connection will be established from the moment the request is sent until the Function execution finishes its execution and returns its response. This is great if the process takes just a few seconds (no more than 5-10 seconds). For longer processes, the connection will probably time out, and you won't receive any response. For these cases, you should consider switching to asynchronous invocation.

To invoke a Function synchronously, make a request to the following endpoint:

/spaces/<space>/functions/<function_name>/invoke

Note: Methods allowed are POST, GET, PUT, PATCH, and DELETE

You can add any query parameters your Function may need to work with to this URL. You can also append to the URL a custom path (up to three levels)

Example:

GET/spaces/<space>/functions/<function_name>/invoke/stock/market/today?company=Google

The function will receive /stock/market/today as the request's path and will return today's Google stock prices.

Asynchronous Invocation

When you invoke a function asynchronously, you're not waiting for it to finish its task before moving on. Instead, you let it run in the background while your workflow continues. This can be beneficial when you have tasks that don't need immediate results or when you want to parallelize operations to improve overall efficiency. However, you might need to handle the function's outcome differently, as it might not be immediately available.

/spaces/<space>/functions/<function_name>/async-invoke will invoke your Function asynchronously, which is best suited for long-running tasks. That means your Function will run and send the response as a request to the URL you choose.

To make an asynchronous invocation, you need to tell the Function where you want to receive the response adding a callback URL to your request. This callback URL will be added in a header called X-Callback-Url.

After sending the request to the asynchronous invocation endpoint, you'll get a 202 response immediately meaning that the request was accepted. Your Function will perform its task and, when finished, it will send the response as a request to the URL you specified in the X-Callback-Url header. This request will contain the Function output in the body, all the headers you've set inside your function and an additional X-Function-Status header with the response status code.

The endpoint to asynchronously invoke a Function is

/spaces/<space>/functions/<function_name>/async-invoke
Note: The only method allowed in this case is POST.

As with synchronous invocation, you can use query parameters and custom extended paths in your requests when asynchronously invoking your Functions.