Detailed Usage

This is a more detailed explanation of the main commands you'll use in Oracle Functions as a developer.

Create an Application

An application is essentially a grouping of functions, that put together, form an API. Here's how to create an app.

fn apps create myapp

Or using a cURL:

curl -H "Content-Type: application/json" -X POST -d '{
    "app": { "name":"myapp" }
}' http://localhost:8080/v1/apps

Add a Route

A route is a way to define a path in your application that maps to a function. In this example, we'll map /hello to a simple Hello World! function called funcy/hello which is a function we already made that you can use -- yes, you can share functions! The source code for this function is in the examples directory. You can read more about writing your own functions here.

fn routes create myapp /hello -i funcy/hello

Or using cURL:

curl -H "Content-Type: application/json" -X POST -d '{
    "route": {
        "path":"/hello",
        "image":"funcy/hello"
    }
}' http://localhost:8080/v1/apps/myapp/routes

Calling your Function

Calling your function is as simple as requesting a URL. Each app has its own namespace and each route mapped to the app. The app myapp that we created above along with the /hello route we added would be called via the following URL: http://localhost:8080/r/myapp/hello

Either surf to it in your browser or use fn:

fn call myapp /hello

Or using a cURL:

curl http://localhost:8080/r/myapp/hello

Passing data into a function

Your function will get the body of the HTTP request via STDIN, and the headers of the request will be passed in as env vars. You can test a function with the CLI tool:

echo '{"name":"Johnny"}' | fn call myapp /hello

Or using cURL:

curl -H "Content-Type: application/json" -X POST -d '{
    "name":"Johnny"
}' http://localhost:8080/r/myapp/hello

You should see it say Hello Johnny! now instead of Hello World!.

Add an asynchronous function

Oracle Functions supports synchronous function calls like we just tried above, and asynchronous for background processing.

Asynchronous functions are great for tasks that are CPU heavy or take more than a few seconds to complete. For instance, image processing, video processing, data processing, ETL, etc. Architecturally, the main difference between synchronous and asynchronous is that requests to asynchronous functions are put in a queue and executed on upon resource availability so that they do not interfere with the fast synchronous responses required for an API. Also, since it uses a message queue, you can queue up millions of function calls without worrying about capacity as requests will just be queued up and run at some point in the future.

To add an asynchronous function, create another route with the "type":"async", for example:

curl -H "Content-Type: application/json" -X POST -d '{
    "route": {
        "type": "async",
        "path":"/hello-async",
        "image":"funcy/hello"
    }
}' http://localhost:8080/v1/apps/myapp/routes

or set type: async in your func.yaml.

Now if you request this route:

curl -H "Content-Type: application/json" -X POST -d '{
    "name":"Johnny"
}' http://localhost:8080/r/myapp/hello-async

You will get a call_id in the response:

{"call_id":"572415fd-e26e-542b-846f-f1f5870034f2"}

If you watch the logs, you will see the function actually runs in the background:

3.7 KiB Raw Blame History