api.fabaccess-api/main.capnp

@0xbf017710be5a54ff;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

using Authentication = import "auth.capnp".Authentication;
using Resources = import "resources.capnp".Resources;
using Users = import "users.capnp".Users;

struct Version
{
    major @0 :Int32 = 0;
    minor @1 :Int32 = 4;
}

interface Bootstrap
{
    getAPIVersion @0 () -> Version;

    getServerRelease @1 () -> ( name :Text, release :Text );
    # Returns the server implementation name and version/build number
    # Designed only for human-facing debugging output so should be informative
    # over machine-readable.
    # Example: ("bffhd", "0.3.1-f397e1e [rustc 1.57.0 (f1edd0429 2021-11-29)]")

    mechanisms @2 () -> ( mechs :List(Text) );
    # Get a list of Mechanisms this server allows in this context.

    createSession @3 ( mechanism :Text, initialData :Data )
        -> ( authentication :Authentication );
    # Create a new session with the server that you wish to authenticate using
    # `mechanism`.  If the mechanism is a client-first mechanism you MAY set
    # `initialData` to contain the data you want to send.  If the mechanism is
    # server-first or you do not wish to send initial data, make initialData a
    # NULL-pointer.
}

struct Session {
    # An API session with the server.  The below capabilities are set to NULL if
    # the authenticated user doesn't have permission to access the system in
    # question, or if the server does not implement it.

    resources @0 :Resources;
    # Access to the resources configured.

    users @1 :Users;
    # User administration.  This includes both modifying other users and
    # self-modification, so this is allowed for most sessions
}