API functions

Caution

Currently, this is an experimental feature as such, it may be subject to breaking changes and may present unidentified security issues. Do not rely on this feature in production applications. To enable this, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to define_api.

Overview

API functions are passed in as middleware inside a DEFINE API or DEFINE CONFIG API statement and called a request is received.

The only API function intended for use in regular queries is the api::invoke function, which is used to test API endpoints instead of as middleware.

The signatures for all other functions are presented here are from the point of view of the user. For example, the api::timeout function takes a single duration.

api::timeout(duration)

In practice, two extra arguments are passed in to these functions unseen to the user, making this the true signature.

api::timeout($req: object, $next: function, $duration: duration)

For more details on how this works, see this section of the page.

api::invoke

API DEFINITION
api::invoke($path: string, $options: option<object>) -> object

The api::invoke function invokes a custom /api endpoint defined using a DEFINE API statement. While a DEFINE API statement creates an API endpoint at the /api/:namespace/:database/:endpoint path, this function is called when a namespace and database have already been decided, necessitating only the final path (such as "/test") for it to be invoked.

The following two examples of the function assume that this DEFINE API statement has been used to set up the "/test" endpoint.

Define API endpoint
DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::timeout(1s)
        THEN {
            {
                status: 404,
                body: $request.body,
                headers: { the_time_is_now: <string>time::now() }
            };
        };

Calling the api::invoke function with just a path:

Use defined endpoint
api::invoke("/test");

Output
{
	body: NONE,
    context: {},
	headers: {
		the_time_is_now: '2025-12-25T11:49:30.732Z'
	},
	status: 404
}

Calling the api::invoke function with a path and an object containing a body and headers:

api::invoke("/test", {
    body: <bytes> '{ "a": true }',
    headers: {
        "Content-Type": "application/json",
        Accept: "application/cbor",
    }
});

Output
{
	body: b"7B202261223A2074727565207D",
    context: {},
	headers: {
		the_time_is_now: '2025-12-25T11:51:18.910Z'
	},
	status: 404
}

For more information and examples, see the page for the DEFINE API statement.

api::timeout

The api::timeout function sets the maximum timeout for a request.

API DEFINITION
api::timeout(duration)

The following example will always return an error because the

Example
DEFINE API "/exceeds_timeout"
    FOR get 
        MIDDLEWARE
            api::timeout(1ns)
        THEN {
            sleep 1ns;
            {}
        };

api::req::body

API DEFINITION
api::req::body($path: string, $strategy: option<string>)

This function sets the strategy (the input format) for the endpoint. It can take one of the following strings:

• ‘auto’
• ‘json’
• ‘cbor’
• ‘flatbuffers’
• ‘plain’
• ‘bytes’
• ‘native’

The following example shows an endpoint for each of these strategies, followed by an invocation for each that matches it.

DEFINE API "/body/json" FOR post
    MIDDLEWARE api::req::body("json")
    THEN {{ body: { parsed: $request.body } }};

DEFINE API "/body/cbor" FOR post
    MIDDLEWARE api::req::body("cbor")
    THEN {{ body: { parsed: $request.body } }};

DEFINE API "/body/plain" FOR post
    MIDDLEWARE api::req::body("plain")
    THEN {{ body: { parsed: $request.body } }};

DEFINE API "/body/bytes" FOR post
    MIDDLEWARE api::req::body("bytes")
    THEN {{ body: { parsed: $request.body } }};

DEFINE API "/body/native" FOR post
    MIDDLEWARE api::req::body("native")
    THEN {{ body: { parsed: $request.body } }};

DEFINE API "/body/auto" FOR post
    MIDDLEWARE api::req::body("auto")
    THEN {{ body: { parsed: $request.body } }};

api::invoke("/body/json", {
    method: "post",
    headers: { "content-type": "application/json" },
    body: <bytes>'{"name":"billy","billys_number":753}'
});

api::invoke("/body/cbor", {
    method: "post",
    headers: { "content-type": "application/cbor" },
    body: encoding::cbor::encode('CBOR!!')
});

api::invoke("/body/plain", {
    method: "post",
    headers: { "content-type": "text/plain" },
    body: <bytes>'plain text content'
});

api::invoke("/body/bytes", {
    method: "post",
    headers: { "content-type": "application/octet-stream" },
    body: <bytes>'raw bytes'
});

api::invoke("/body/native", {
    method: "post",
    headers: { "content-type": "application/vnd.surrealdb.native" },
    body: { native: "format" }
});

api::invoke("/body/auto", {
    method: "post",
    headers: { "content-type": "application/json" },
    body: <bytes>'{"auto":"json"}'
});

api::invoke("/body/auto", {
    method: "post",
    body: <bytes>'some data'
});

api::res::body

API DEFINITION
api::res::body($path: string, $strategy: option<string>)

DEFINE API "/serialize_json"
    FOR get
        MIDDLEWARE
            api::res::body("json")
        THEN {
            {
                status: 200,
                body: {
                    message: "Hello"
                }
            };
        };

api::invoke("/serialize_json").{
    body: <string>body, -- Cast response bytes into string
    headers,
    status
};

Response
{ 
    body: '{"message":"Hello"}', 
    headers: { "access-control-allow-origin": '*', "content-type": 'application/json' }, 
    status: 200 
}

api::res::header

The api::res::header function sets a single header for a response.

API DEFINITION
api::res::header($header_name: string, $val: value)

Example
DEFINE API "/test"
  FOR get 
    MIDDLEWARE
      api::res::header("country-origin", "CA")
    THEN {
      {
        status: 200,
        headers: {
          "requested-at": <string>time::now()
        },
        body: SELECT * FROM person
      };
    };

api::res::headers

The api::res::headers function takes an object to set the headers for a response.

API DEFINITION
api::res::headers(object)

Example
DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::res::headers({
                "country-origin": "CA",
                "language": "FR"
            })
        THEN {
            {
                status: 200,
                headers: {
                    "requested-at": <string>time::now()
                },
                body: SELECT * FROM person
            };
        };

api::res::status

API DEFINITION
api::res::status(int)

The api::res::status function adds a status to the response of an API endpoint.

DEFINE API "/always_ok"
    FOR get
        MIDDLEWARE
            api::res::status(200)
        THEN {
            {
                status: 404,
                body: {
                    some: "data"
                }
            };
        };

api::invoke("/always_ok");

Response
{ 
    body: {some: 'data'}, 
    context: {}, 
    headers: {}, 
    status: 200 
}

Setting an invalid HTTP status will result in an error.

DEFINE API "/status/invalid-low"
    FOR get
        MIDDLEWARE
            api::res::status(99)
        THEN {
            RETURN {
                status: 200,
                body: {}
            };
        };

api::invoke("/status/invalid-low");

Response
'Invalid HTTP status code: 99. Must be between 100 and 599'

Custom middleware

A DEFINE FUNCTION statement can be used to define a function for use as custom middleware. For more details on defining a custom function in this manner, see the DEFINE API page.

Structure of API functions

An API function can technically be called in the same way as any other function, as long as the first argument is an object and the second argument is a closure that returns an object. After a MIDDLEWARE clause these arguments will be automatically filled, but dummy arguments can be passed in for practice or testing.

api::res::body({}, || {}, "json").{
    body: <string>body,
    context,
    headers,
    status
};

-- Returns:
{
	body: 'null',
	context: {},
	headers: {
		"content-type": 'application/json'
	},
	status: 200
};

api::res::body({}, || {}, "jsonnn").{
    body: <string>body,
    context,
    headers,
    status
};

-- Returns:
'Failed to decode BodyStrategy, no variants matched'