Skip to main content

Actions API

The Nexigon Actions API is the primary interface for interacting with Nexigon. Each operation—whether it's querying data, managing resources, or triggering domain-specific workflows—is represented as a clearly defined action. An action is a self-contained unit of intent defining what should be done, independent of who does it or how it is done. Built with developers in mind, the Actions API makes it easy to build, automate, and maintain robust integrations with Nexigon.

While many modern APIs follow a RESTful design bound to HTTP, the Actions API follows a transport-agnostic, RPC-style model that we believe to be a better fit for Nexigon's architecture and goals. For HTTP-based integrations, we provide a formal OpenAPI specification that covers the entire API surface and allows developers to tap into the broad ecosystem of existing tools.

info

Check out the API docs for Nexigon's HTTP API.

Core Concepts​

The Actions API is built around a small number of composable core concepts:

  • Actions: An action is a single, well-defined operation that can be invoked within Nexigon. Each action has an input type (the data it requires) and an output type (the data it returns). Actions are self-contained and describe what should happen.
  • Action Names: Every action has a unique, descriptive action name composed of a namespace prefix (e.g., users_) followed by an operation name in PascalCase (e.g., CreateUser). Together, these identify the action at the API surface.
  • Input and Output Types: All input and output types are formally specified using our in-house Interface Definition Language Sidex. The Sidex definition is used to generate idiomatic Rust and TypesScript types as well as JSON Schema. This enables end-to-end type safety as well as the generation of the OpenAPI specification (which is based on JSON Schema).
  • Invocations: An invocation is the act of calling an action with specific input data. The transport layer is responsible for delivering the invocation and returning the corresponding output or any errors (see below) that may occur.
  • Actors: An actor represents an entity (e.g., a user) who invokes an action, along with additional authentication information.

For the purposes of the API, we distinguish the following kinds of errors:

  • Internal Errors: Errors that occur within Nexigon and that are beyond the control of the API user. These are not part of an action’s output type and are typically reported as generic failures with an error message.
  • Transport Errors: Errors that occur at the transport layer, such as malformed responses or communication failures. Like internal errors, these are not represented in the action's output type.
  • Contract Errors: Errors resulting from improper API usage, such as calling an action without proper permissions or supplying invalid data. Like internal errors, these are not represented in the action's output type.
  • Expected Errors: Application-level errors that may occur during normal use (e.g., attempting to create a user with an already existing email address). These are explicitly encoded in an action’s output type and should always be handled by clients.

Transport Layer​

The Actions API is designed to be transport-agnostic: actions are defined independently of how they are transmitted or invoked. This separation allows the same set of actions to be integrated across different protocols.

HTTP​

In practice, the most common transport is HTTP. When used over HTTP, each action is invoked via a POST request to a distinct URL that includes the action name. The request body must contain a JSON object that conforms to the action’s input type. The response is a JSON object that either contains the action’s output or a structured error envelope. The status code 200 is used to communicate that the response conforms to the action's output type, including possible expected errors. As usual, codes from the 400 and 500 family are used to communicate contract, internal, and possibly transport errors.

Example​

To invoke the users_CreateUser action over HTTP, a client sends a request like:

// POST /api/v1/actions/invoke/users_CreateUser HTTP/1.1
// Content-Type: application/json
// Authorization: Bearer <token>
{
  "email": "alice@example.com",
  "displayName": "Alice"
}

If the action completes successfully, the response might look like:

// 200 OK
{
    "result": "Created",
    "userId": "u_qEX2YRdLYRy244uaCdYBn9"
}

If a user with the email address already exists (expected error), the response might look like:

// 200 OK
{
    "result": "EmailAlreadyExists"
}

If the the request lacks proper authorization (contract error), the response may look like:

// 403 Forbidden
{
    "error": "Forbidden",
    "message": "Actor does not have the required permissions."
}

If there was an internal error, the response may look like:

// 500 Internal Server Error
{
    "error": "Internal",
    "message": "Error connecting to database."
}

Note that clients must not assume that responses other than 200 OK contain a valid JSON payload as those responses may also be generated by HTTP intermediaries, e.g., proxies or load balancers, which may use other formats.