Skip to main content

Endpoint

An Endpoint represents a behavior of an Application that can be invoked. The behavior can be described with a sequence of Statements.

Sysl supports two kinds of Endpoint:

  • RPC: A function that can be invoked remotely. Parameters are specified in the function signature.
  • REST: A function mapped to a URL with a specific path and HTTP method. Parameters can be specified in three ways:
    • Path parameters: /foo/bar/{param <: int}. Types must be primitive.
    • Query parameters: GET ?foo=int&bar={TypeName}. Types may be primitive (bare) or references (wrapped in curly braces).
    • Payload parameters: POST (foo <: string [~body], head <: TypeName [~header], bar <: int [~cookie]). Can contain header, cookie and body content, identified by the corresponding Tags.

Syntax#

At a minimum, an RPC endpoint is represented by its name and the placeholder Statement (...):

# An Application with a "Withdraw" RPC Endpoint.Bank:    Withdraw:        ...

The Endpoint can be followed by parentheses containing a specification of the input Parameters. Each Parameter is simply a name and a Type, much like a Field.

Bank:    # An RPC Endpoint that takes two inputs.    Withdraw(accountNumber <: string, amount <: int):        ...
    # An RPC Endpoint that explicitly takes no inputs.    Logout():        ...

REST Endpoint specifications are similar, but are described by their path with a nested HTTP method. Paths can be nested to The HTTP method can be one of GET, PUT, POST, DELETE or PATCH.

Bank:    # Get details of an account.    /account/{accountNumber <: int}:        # Query params can be specified on the method.        GET ?from=date&to=date:            ...
        # This path builds on the parent path above, withdrawing from that account.        /withdraw:            POST (Transaction):                ...
    # The schema of the POST request body.    !type Transaction:        amount <: int

To make a parameter optional, append a suffix ? to the type, e.g.

  • Path parameters: /foo/bar/{param <: int?}
  • Query parameters: GET ?foo=int?&bar={TypeName}?
  • Payload parameters: POST (foo <: string? [~body], head <: TypeName? [~header]).

See also#