Skip to main content

Use SE2's APIs

info

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

Using SE2 from Go​

The se2-go library helps you easily interact with SE2's APIs from your Go application. 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 se2-go on pkg.go.dev. Those docs are generated from inline comments in the se2-go source code.

Install SE2 for Go​

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

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

Basic Usage​

Configuration​

This example sets up a basic client with the token generated in Subo or with the web app. The se2.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/se2-go"
)

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

    return client
}

Build and run a extension​

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

Behind the scenes, se2-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/se2-go"
)

func main() {
    client := client()

    // This is a local reference to some SE2 module. Nothing has run in SE2 at this point.
    runnable := se2.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.BuildExtensionString(runnable, template.Contents)

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

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

    // Execute the extension
    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 extensions and execute one.

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

async extension listAvailableExtensions() {
    const extensionList = await suborbital.admin.getExtensions({
        userId: "1234",
        namespace: "default",
    });

    console.log("Extensions:", extensions);
}

Example output​

{
    "extensions": [
        {
            "name": "foo",
            "namespace": "...",
            "lang": "...",
            "version": "...",
            "draftVersion": "...",
            "apiVersion": "...",
            "fqext": "...",
            "fqextURI": "...",
        }
    ]
}

The result includes a extension 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, extName, and version, and returns the result of the executed extension.

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

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

Full API​

These are all of the available methods.

Admin​

suborbital.admin.getToken​

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

suborbital.admin.getExtensions​

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

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

suborbital.admin.getExtensionResults​

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

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

suborbital.admin.getExtensionErrors​

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

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

Exec​

suborbital.exec.run​

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

Builder​

suborbital.builder.build​

Description: Builds the provided code using the specified language toolchain.
Args: An object containing language, environment, userId, namespace, extName, 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, extName, token.
Result: A specified runnable.

suborbital.builder.deployDraft​

Description: Deploys the specified runnable.
Args: An object containing environment, userId, namespace, extName, 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, extName.
Result: A string containing the result.

suborbital.builder.getTemplate​

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

import { logInfo } from "@suborbital/suborbital"

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

    let out = "Hello there, " + inStr

    return String.UTF8.encode(out)
}