Skip to main content

Using SE2's APIs

You can find a detailed specification of SE2's APIs here.

Using SE2 from Go​

The compute-go library helps you easily interact with SE2's APIs from your Go application. Suborbital SE2 is designed to run alongside your application in a Kubernetes or Docker Compose environment.

Documentation​

Like most Go packages, you can find complete and up to date technical documentation for compute-go on pkg.go.dev. Those docs are generated from inline comments in the compute-go source code.

Installation​

In a directory with a go.mod file, run:

go get github.com/suborbital/compute-go@latest

Basic Usage​

Configuration​

This example sets up a basic client with the token generated in Subo or with the web app. The compute.Client object created here assumes that SE2 is running on the same host on its default ports. Feel free to check out the code for this example!

client.go
package main

import (
    "os"

    "github.com/suborbital/compute-go"
)

func client() *compute.Client {
    token, _ := os.LookupEnv("SCC_ENV_TOKEN")
    client, _ := compute.NewClient(compute.LocalConfig(), token)

    return client
}

Build and run a function​

We can now integrate SE2 into an application. compute-go has access to all of SE2's APIs. It can run builds, list existing functions, run tests, and execute functions.

Behind the scenes, compute-go manages authentication, so you don't have to worry about setting the right HTTP headers when interacting with the SE2 API.

app.go
package main

import (
    "log"

    "github.com/suborbital/compute-go"
)

func main() {
    client := client()

    // This is a local reference to some SE2 module. Nothing has run in SE2 at this point.
    runnable := compute.NewRunnable("com.suborbital", "acmeco", "default", "rs-hello-world", "rust")

    // Request template source code for the above SE2 module.
    template, _ := client.BuilderTemplate(runnable)

    // Log the default 'hello world' Rust template to stdout
    log.Println(template.Contents)

    // Run a remote build for the provided SE2 module and the unmodified 'hello world'
    // template source code.
    build, _ := client.BuildFunctionString(runnable, template.Contents)

    if !build.Succeeded {
        // Log the compiler output to see why the build failed
        log.Fatal(build.OutputLog)
    }

    // Deploy the function (the runnable's .Version field is adjusted here)
    client.PromoteDraft(runnable)

    // Execute the function
    result, _ := client.ExecString(runnable, "world!")

    // Log the execution output
    log.Println(string(result))
}

Now that the SE2 module has been built, it can be executed as much as you like without rebuilding using client.Exec or client.ExecString.

Getting started​

Using the SE2 APIs, this guide will use the Administrative and Execution APIs to get a list of available functions and execute one.

The Administrative APIs getFunctions method takes an object with a userId and a namespace and returns a list of available functions for that user in the provided namespace.

async function listAvailableFunctions() {
    const functionList = await suborbital.admin.getFunctions({
        userId: "1234",
        namespace: "default",
    });

    console.log("Functions:", functions);
}

Example output​

{
    "functions": [
        {
            "name": "foo",
            "namespace": "...",
            "lang": "...",
            "version": "...",
            "draftVersion": "...",
            "apiVersion": "...",
            "fqfn": "...",
            "fqfnURI": "...",
        }
    ]
}

The result includes a function named foo (which for this tutorial already exists) and which we will execute using the Execution APIs run method.

The run method takes an object with the environment, userId, namespace, fnName, and version, and returns the result of the executed function.

async function runFunction() {
    const result = await suborbital.exec.run({
        environment: "com.acmeco",
        userId: "1234",
        namespace: "default",
        fnName: "foo",
        version: "v1.0.0",
    });

    console.log("Function output:", result);
}

Full API​

These are all of the available methods.

Admin​

suborbital.admin.getToken​

Description: Retrieves an authentication token for the given function, typically used to authenticate calls to the Builder API.
Args: An object containing environment, userId, namespace, fnName.
Result: A string containing the token used for authorization.

suborbital.admin.getFunctions​

Description: Returns a list of available functions for the given user in the given namespace.
Args: An object containing userId, namespace.
Result:

{
    "functions": [
        {
            "name": "foo",
            "namespace": "...",
            "lang": "...",
            "version": "...",
            "draftVersion": "...",
            "apiVersion": "...",
            "fqfn": "...",
            "fqfnURI": "...",
        }
    ]
}

suborbital.admin.getFunctionResults​

Description: Returns the most recent results (up to 5) produced by the execution of the given function.
Args: An object containing environment, userId, namespace, fnName, version.
Result:

{
    "results": [
        {
            "uuid": "...",
            "timestamp": "...",
            "response": "..."
        }
    ]
}

suborbital.admin.getFunctionErrors​

Description: Returns the most recent errors (up to 5) produced by the execution of the given function.
Args: An object containing environment, userId, namespace, fnName, version.
Result:

{
    "errors": [
        {
            "uuid": "...",
            "timestamp": "...",
            "code": 400,
            "message": "..."
        }
    ]
}

Exec​

suborbital.exec.run​

Description: Executes the given function, with the provided body, params and state loaded into the function at runtime.
Args: An object containing environment,userId,namespace, fnName,version.
Result: The result of the executed function.

Builder​

suborbital.builder.build​

Description: Builds the provided code using the specified language toolchain.
Args: An object containing language, environment, userId, namespace, fnName, token.
Result: A string containing the logs for the build.

suborbital.builder.getDraft​

Description: Gets the draft for the specified runnable.
Args: An object containing environment, userId, namespace, fnName, token.
Result: A specified runnable.

suborbital.builder.deployDraft​

Description: Deploys the specified runnable.
Args: An object containing environment, userId, namespace, fnName, token.
Result: A string containing the version.

suborbital.builder.testDraft​

Description: Tests the draft for the specified runnable.
Args: An object containing environment, userId, namespace, fnName.
Result: A string containing the result.

suborbital.builder.getTemplate​

Description: Gets the template (which controls what your users see when they create a new function) for a new function of the given language.
Args: An object containing fnName, language.
Result:

import { logInfo } from "@suborbital/suborbital"

export function run(input: ArrayBuffer): ArrayBuffer {
    let inStr = String.UTF8.decode(input)

    let out = "Hello there, " + inStr

    return String.UTF8.encode(out)
}