API functions

Note

API middleware functions such as api::req::max_body cannot be used in an ad-hoc manner, such as via Surrealist or the CLI. Instead, they are passed in to a DEFINE API or DEFINE CONFIG API statement to be used as middleware when a request is received. The only function that can be run at any time is api::invoke which is used to test API endpoints.

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.

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::req::raw_body(false)
        THEN {
            RETURN {
                status: 404,
                body: $request.body,
                headers: { the_time_is_now: time::now() }
            };
        };

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

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

Output
{
	body: NONE,
	headers: {
		the_time_is_now: '2025-02-25T11:49:30.732Z'
	},
	raw: false,
	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: encoding::base64::decode("eyAiYSI6IHRydWUgfQ"),
	headers: {
		the_time_is_now: '2025-02-25T11:51:18.910Z'
	},
	raw: false,
	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)

Example
DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::timeout(1s)
        THEN {
            RETURN {
                headers: {
                    "requested-at": time::now()
                },
                body: SELECT * FROM person
            };
        };

api::req::max_body

The api::req::max_body function sets the maximum allowed body size in bytes for a request made.

API DEFINITION
api::req::max_body(string)

The string argument for this function must be a number followed by the type of unit: b, kb, mb, gb, tb, or pb.

Example
DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::req::max_body("1000b")
        THEN {
            RETURN {
                headers: {
                    "requested-at": time::now()
                },
                body: SELECT * FROM person
            };
        };

api::req::raw_body

The api::req::raw_body function sets whether to only accept a raw body composed of bytes, a setting which is normally set to false. If this function is caled with no argument, it will be set to true.

API DEFINITION
api::req::raw_body(option<bool>)

Example
DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::req::raw_body(true)
        THEN {
            RETURN {
                headers: {
                    "requested-at": time::now()
                },
                body: SELECT * FROM person
            };
        };

-- Now must be invoked with a body in bytes
api::invoke("/test", {
    body: <bytes>"Hi plz send the information"
});

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 {
            RETURN {
                headers: {
                    "requested-at": 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 {
            RETURN {
                headers: {
                    "requested-at": time::now()
                },
                body: SELECT * FROM person
            };
        };

api::res::raw_body

The api::res::raw_body function sets whether to send a raw body composed of bytes, a setting which is normally set to false. If this function is caled with no argument, it will be set to true.

API DEFINITION
api::res::raw_body(option<bool>)

Example
DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::res::raw_body(true)
        THEN {
            RETURN {
                headers: {
                    "requested-at": time::now()
                },
                body: SELECT * FROM person
            };
        };