C API Reference

C API Reference v0.17.0¶

Functions¶

spikard_schema_query_only()¶

Create a simple schema configuration with only Query type.

This is a convenience function for schemas that only have queries.

Returns:

A QueryOnlyConfig with default settings

Signature:

SPIKARDAlefHandle spikard_schema_query_only();

Example:

SPIKARDAlefHandle result = spikard_schema_query_only();

Returns: SPIKARDAlefHandle

spikard_schema_query_mutation()¶

Create a schema configuration with Query and Mutation types.

This is a convenience function for schemas with queries and mutations but no subscriptions.

Returns:

A QueryMutationConfig with default settings

Signature:

SPIKARDAlefHandle spikard_schema_query_mutation();

Example:

SPIKARDAlefHandle result = spikard_schema_query_mutation();

Returns: SPIKARDAlefHandle

spikard_schema_full()¶

Create a schema configuration with all three root types.

This is a convenience function for fully-featured schemas.

Returns:

A FullSchemaConfig with default settings

Signature:

SPIKARDAlefHandle spikard_schema_full();

Example:

SPIKARDAlefHandle result = spikard_schema_full();

Returns: SPIKARDAlefHandle

Types¶

SPIKARDApiKeyAuthConfig¶

C representation: SPIKARDApiKeyAuthConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDApiKeyAuthConfig does not appear anywhere in the generated header.

Per-route API key authentication requirement.

Mirrors spikard_http.ApiKeyConfig for the same reason JwtAuthConfig mirrors spikard_http.JwtConfig: spikard-core cannot depend on spikard-http.

SPIKARDApiKeyConfig¶

C representation: SPIKARDApiKeyConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDApiKeyConfig does not appear anywhere in the generated header.

API Key authentication configuration

SPIKARDAsyncApiConfig¶

C representation: SPIKARDAsyncApiConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDAsyncApiConfig does not appear anywhere in the generated header.

AsyncAPI HTTP endpoint configuration

SPIKARDAuthorizationConfig¶

C representation: SPIKARDAuthorizationConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDAuthorizationConfig does not appear anywhere in the generated header.

Per-route roles/scopes/permissions authorization requirement.

spikard_http.auth.Claims does not yet carry roles, scopes, or permissions, so nothing can enforce this today. This type only defines the requirement shape; a later phase must extend Claims (or an equivalent claims-decoding path) to populate them before enforcement is possible.

Deserialization goes through AuthorizationConfigRepr rather than a derive so the fixture's singular {"required_role": "admin"} shape (fixtures/problem_details.json's problem_details_403_forbidden) populates required_roles instead of being silently dropped as an unrecognized field — a config that parses to "no constraint" from real authorization data is a vacuous-pass bug, not a compatibility shim. deny_unknown_fields on the repr means any other unrecognized key is a loud deserialize error instead.

SPIKARDBackgroundJobMetadata¶

C representation: SPIKARDBackgroundJobMetadata is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDBackgroundJobMetadata does not appear anywhere in the generated header.

SPIKARDBackgroundTaskConfig¶

C representation: SPIKARDBackgroundTaskConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDBackgroundTaskConfig does not appear anywhere in the generated header.

Configuration for in-process background task execution.

SPIKARDCompressionConfig¶

C representation: SPIKARDCompressionConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDCompressionConfig does not appear anywhere in the generated header.

Compression configuration shared across runtimes

SPIKARDContactInfo¶

C representation: SPIKARDContactInfo is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDContactInfo does not appear anywhere in the generated header.

Contact information

SPIKARDCorsConfig¶

C representation: SPIKARDCorsConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDCorsConfig does not appear anywhere in the generated header.

CORS configuration for a route

SPIKARDDynamicSchemaConfig¶

C representation: SPIKARDDynamicSchemaConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDDynamicSchemaConfig does not appear anywhere in the generated header.

Configuration for building and executing a dynamic-SDL schema.

SPIKARDFieldErrorSpec¶

C representation: SPIKARDFieldErrorSpec is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDFieldErrorSpec does not appear anywhere in the generated header.

A field-level error to inject at a specific response path.

path is the dot-separated sequence of field names from the operation root to the field that should fail, e.g. "user" for a top-level field or "order.customer" for a nested one.

SPIKARDFullSchemaConfig¶

C representation: SPIKARDFullSchemaConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDFullSchemaConfig does not appear anywhere in the generated header.

Configuration for fully-featured schemas with Query, Mutation, and Subscription types

SPIKARDGraphQlRouteConfig¶

C representation: SPIKARDGraphQlRouteConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDGraphQlRouteConfig does not appear anywhere in the generated header.

Configuration for GraphQL routes

Provides a builder pattern for configuring GraphQL route parameters for the Spikard HTTP server's routing system.

Methods¶

spikard_graph_ql_route_config_new()¶

Create a new GraphQL route configuration with defaults

Default values:

• path: "/graphql"
• method: "POST"
• enable_playground: false

Signature:

SPIKARDAlefHandle spikard_graph_ql_route_config_new();

Example:

SPIKARDAlefHandle result = spikard_graph_ql_route_config_new();

Returns: SPIKARDAlefHandle

spikard_graph_ql_route_config_path()¶

Set the HTTP path for the GraphQL endpoint

Signature:

SPIKARDAlefHandle spikard_graph_ql_route_config_path(SPIKARDAlefHandle this, const char* path);

Example:

SPIKARDAlefHandle result = spikard_graph_ql_route_config_path(instance, "value");

Parameters:

Returns: SPIKARDAlefHandle

spikard_graph_ql_route_config_method()¶

Set the HTTP method for the GraphQL endpoint

Signature:

SPIKARDAlefHandle spikard_graph_ql_route_config_method(SPIKARDAlefHandle this, const char* method);

Example:

SPIKARDAlefHandle result = spikard_graph_ql_route_config_method(instance, "value");

Parameters:

Returns: SPIKARDAlefHandle

spikard_graph_ql_route_config_enable_playground()¶

Enable or disable the GraphQL Playground UI

Signature:

SPIKARDAlefHandle spikard_graph_ql_route_config_enable_playground(SPIKARDAlefHandle this, int32_t enable);

Example:

SPIKARDAlefHandle result = spikard_graph_ql_route_config_enable_playground(instance, true);

Parameters:

Returns: SPIKARDAlefHandle

spikard_graph_ql_route_config_description()¶

Set a custom description for documentation

Signature:

SPIKARDAlefHandle spikard_graph_ql_route_config_description(SPIKARDAlefHandle this, const char* description);

Example:

SPIKARDAlefHandle result = spikard_graph_ql_route_config_description(instance, "value");

Parameters:

Returns: SPIKARDAlefHandle

spikard_graph_ql_route_config_get_path()¶

Get the configured path

Signature:

const char* spikard_graph_ql_route_config_get_path(SPIKARDAlefHandle this);

Example:

const char *result = spikard_graph_ql_route_config_get_path(instance);

Returns: const char*

spikard_graph_ql_route_config_get_method()¶

Get the configured method

Signature:

const char* spikard_graph_ql_route_config_get_method(SPIKARDAlefHandle this);

Example:

const char *result = spikard_graph_ql_route_config_get_method(instance);

Returns: const char*

spikard_graph_ql_route_config_is_playground_enabled()¶

Check if playground is enabled

Signature:

int32_t spikard_graph_ql_route_config_is_playground_enabled(SPIKARDAlefHandle this);

Example:

int32_t result = spikard_graph_ql_route_config_is_playground_enabled(instance);

Returns: int32_t

spikard_graph_ql_route_config_get_description()¶

Get the description if set

Signature:

const char* spikard_graph_ql_route_config_get_description(SPIKARDAlefHandle this);

Example:

const char* result = spikard_graph_ql_route_config_get_description(instance);

Returns: const char*

SPIKARDGrpcConfig¶

C representation: SPIKARDGrpcConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDGrpcConfig does not appear anywhere in the generated header.

Configuration for gRPC support

Controls how the server handles gRPC requests, including compression, timeouts, and protocol settings.

Stream Limits¶

This configuration enforces message-level size limits but delegates concurrent stream limiting to the HTTP/2 transport layer:

• Message Size Limits: The max_message_size field is enforced per individual message (request or response) in both unary and streaming RPCs. When a single message exceeds this limit, the request is rejected with PAYLOAD_TOO_LARGE (HTTP 413).

• Concurrent Stream Limits: The max_concurrent_streams is an advisory configuration passed to the HTTP/2 layer for connection-level stream negotiation. The HTTP/2 transport automatically enforces this limit and returns GOAWAY frames when exceeded. Applications should not rely on custom enforcement of this limit.

• Stream Response Size Limits: The max_stream_response_bytes field caps the total encoded bytes emitted across a server-streaming or bidi-streaming response. When the cumulative size exceeds the limit, the stream is terminated with tonic.Status.resource_exhausted. Defaults to NULL (unbounded).

SPIKARDIntoHandler¶

C representation: SPIKARDIntoHandler is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDIntoHandler does not appear anywhere in the generated header.

Convert user-facing handler functions into the low-level Handler trait.

Methods¶

spikard_into_handler_into_handler()¶

Convert this value into a shared request handler.

Signature:

SPIKARDAlefHandle spikard_into_handler_into_handler(SPIKARDAlefHandle this);

Example:

SPIKARDAlefHandle result = spikard_into_handler_into_handler(instance);

Returns: SPIKARDAlefHandle

SPIKARDJsonRpcConfig¶

C representation: SPIKARDJsonRpcConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDJsonRpcConfig does not appear anywhere in the generated header.

JSON-RPC server configuration

SPIKARDJsonRpcMethodInfo¶

C representation: SPIKARDJsonRpcMethodInfo is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDJsonRpcMethodInfo does not appear anywhere in the generated header.

JSON-RPC method metadata for routes that support JSON-RPC

This struct captures the metadata needed to expose HTTP routes as JSON-RPC methods, enabling discovery and documentation of RPC-compatible endpoints.

SPIKARDJwtAuthConfig¶

C representation: SPIKARDJwtAuthConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDJwtAuthConfig does not appear anywhere in the generated header.

Per-route JWT authentication requirement.

spikard-http defines the canonical JwtConfig used by ServerConfig.jwt_auth, but spikard-core cannot depend on spikard-http (the dependency runs the other way), so that type cannot be reused here. This mirrors its fields so a later enforcement phase in spikard-http can convert between the two without losing information.

secret and public_key are both optional because asymmetric algorithms (RS256, ES256, ...) verify against a public key rather than a shared secret; see fixtures/auth.json's jwt_config_algorithm_rs256, which carries public_key and no secret at all. Exactly one is expected to be populated for a given algorithm, but that cross-field invariant is left to a later enforcement phase rather than the type itself.

SPIKARDJwtConfig¶

C representation: SPIKARDJwtConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDJwtConfig does not appear anywhere in the generated header.

JWT authentication configuration

SPIKARDLicenseInfo¶

C representation: SPIKARDLicenseInfo is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDLicenseInfo does not appear anywhere in the generated header.

License information

SPIKARDLifecycleHookRef¶

C representation: SPIKARDLifecycleHookRef is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDLifecycleHookRef does not appear anywhere in the generated header.

A single lifecycle hook reference within a LifecycleHooksConfig phase.

Matches the fixture shape exactly (fixtures/lifecycle_hooks.json, fixtures/di.json): each entry is an object with a required name and handler, an optional list of dependency keys, and an optional free-form config blob (e.g. {"max_requests": 10, "window_seconds": 60} for a rate-limiting hook). deny_unknown_fields turns future fixture drift into a loud error.

SPIKARDLifecycleHooksConfig¶

C representation: SPIKARDLifecycleHooksConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDLifecycleHooksConfig does not appear anywhere in the generated header.

Per-route selection of registered lifecycle hooks.

ServerConfig.lifecycle_hooks holds Arc<dyn LifecycleHook> function pointers and is marked #[serde(skip)] / #[alef(skip)] because closures cannot be serialized or cross the FFI boundary. A per-route field with that same shape would be invisible to alef, and therefore invisible to every binding — defeating the purpose of exposing it here. This descriptor carries LifecycleHookRef entries instead: each one names a registered hook (plus its declared dependencies and optional config), so a later enforcement phase can resolve those names against the server's registered LifecycleHooks and run the matches for this route. The five fields mirror the five hook phases documented in the tower-middleware-and-lifecycle project convention (onRequest, preValidation, preHandler, onResponse, onError).

SPIKARDOpenApiConfig¶

C representation: SPIKARDOpenApiConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDOpenApiConfig does not appear anywhere in the generated header.

OpenAPI configuration

SPIKARDParseRequest¶

C representation: SPIKARDParseRequest is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDParseRequest does not appear anywhere in the generated header.

Request body for POST /asyncapi/parse

SPIKARDParseResult¶

C representation: SPIKARDParseResult is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDParseResult does not appear anywhere in the generated header.

Full parse result returned by POST /asyncapi/parse

SPIKARDParsedChannel¶

C representation: SPIKARDParsedChannel is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDParsedChannel does not appear anywhere in the generated header.

A single channel extracted from an AsyncAPI spec

SPIKARDParsedMessage¶

C representation: SPIKARDParsedMessage is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDParsedMessage does not appear anywhere in the generated header.

A resolved message (name + JSON Schema)

SPIKARDParsedOperation¶

C representation: SPIKARDParsedOperation is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDParsedOperation does not appear anywhere in the generated header.

A single operation extracted from an AsyncAPI spec

SPIKARDProblemDetails¶

C representation: SPIKARDProblemDetails is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDProblemDetails does not appear anywhere in the generated header.

RFC 9457 Problem Details for HTTP APIs

A machine-readable format for specifying errors in HTTP API responses. Per RFC 9457, all fields are optional. The type field defaults to "about:blank" if not specified.

Content-Type¶

Responses using this struct should set:

Content-Type: application/problem+json

{
  "type": "<https://spikard.dev/errors/validation-error>",
  "title": "Request Validation Failed",
  "status": 422,
  "detail": "2 validation errors in request body",
  "errors": [...]
}

SPIKARDQueryMutationConfig¶

C representation: SPIKARDQueryMutationConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDQueryMutationConfig does not appear anywhere in the generated header.

Configuration for schemas with Query and Mutation types

SPIKARDQueryOnlyConfig¶

C representation: SPIKARDQueryOnlyConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDQueryOnlyConfig does not appear anywhere in the generated header.

Configuration for schemas with only Query type

SPIKARDRateLimitConfig¶

C representation: SPIKARDRateLimitConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDRateLimitConfig does not appear anywhere in the generated header.

Rate limiting configuration shared across runtimes

SPIKARDRequest¶

C representation: SPIKARDRequest is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDRequest does not appear anywhere in the generated header.

SPIKARDRequestIdConfig¶

C representation: SPIKARDRequestIdConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDRequestIdConfig does not appear anywhere in the generated header.

Per-route request-id generation/propagation override.

Modeled as a struct rather than Option<bool> on RouteMetadata because the wire shape is an object, not a bare boolean: fixtures/request_id.json's request_id_middleware_can_be_disabled sends {"enabled": false}, which Option<bool> cannot deserialize at all ("invalid type: map, expected a boolean") — the very fixture whose purpose is proving the middleware can be disabled was the one that failed to parse.

SPIKARDResponse¶

C representation: SPIKARDResponse is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDResponse does not appear anywhere in the generated header.

HTTP Response with custom status code, headers, and content

SPIKARDRouteBuilder¶

C representation: SPIKARDRouteBuilder is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDRouteBuilder does not appear anywhere in the generated header.

Builder for defining a route.

Methods¶

spikard_route_builder_new()¶

Create a new builder for the provided HTTP method and path.

Signature:

SPIKARDAlefHandle spikard_route_builder_new(SPIKARDAlefHandle method, const char* path);

Example:

SPIKARDAlefHandle result = spikard_route_builder_new(0, "value");

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_handler_name()¶

Assign an explicit handler name.

Signature:

SPIKARDAlefHandle spikard_route_builder_handler_name(SPIKARDAlefHandle this, const char* name);

Example:

SPIKARDAlefHandle result = spikard_route_builder_handler_name(instance, "value");

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_request_schema_json()¶

Provide a raw JSON schema for the request body.

Signature:

SPIKARDAlefHandle spikard_route_builder_request_schema_json(SPIKARDAlefHandle this, const char* schema);

Example:

SPIKARDAlefHandle result = spikard_route_builder_request_schema_json(instance, NULL);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_response_schema_json()¶

Provide a raw JSON schema for the response body.

Signature:

SPIKARDAlefHandle spikard_route_builder_response_schema_json(SPIKARDAlefHandle this, const char* schema);

Example:

SPIKARDAlefHandle result = spikard_route_builder_response_schema_json(instance, NULL);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_params_schema_json()¶

Provide a raw JSON schema for request parameters.

Signature:

SPIKARDAlefHandle spikard_route_builder_params_schema_json(SPIKARDAlefHandle this, const char* schema);

Example:

SPIKARDAlefHandle result = spikard_route_builder_params_schema_json(instance, NULL);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_file_params_json()¶

Provide multipart file parameter configuration.

Signature:

SPIKARDAlefHandle spikard_route_builder_file_params_json(SPIKARDAlefHandle this, const char* schema);

Example:

SPIKARDAlefHandle result = spikard_route_builder_file_params_json(instance, NULL);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_cors()¶

Attach a CORS configuration for this route.

Signature:

SPIKARDAlefHandle spikard_route_builder_cors(SPIKARDAlefHandle this, SPIKARDAlefHandle cors);

Example:

SPIKARDAlefHandle result = spikard_route_builder_cors(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_compression()¶

Attach a compression configuration for this route.

Signature:

SPIKARDAlefHandle spikard_route_builder_compression(SPIKARDAlefHandle this, SPIKARDAlefHandle compression);

Example:

SPIKARDAlefHandle result = spikard_route_builder_compression(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_body_limit()¶

Attach a per-route maximum request body size in bytes, overriding the server-global default.

Signature:

SPIKARDAlefHandle spikard_route_builder_body_limit(SPIKARDAlefHandle this, uintptr_t max_bytes);

Example:

SPIKARDAlefHandle result = spikard_route_builder_body_limit(instance, 42);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_request_timeout()¶

Attach a per-route request timeout in seconds, overriding the server-global default.

Signature:

SPIKARDAlefHandle spikard_route_builder_request_timeout(SPIKARDAlefHandle this, uint64_t seconds);

Example:

SPIKARDAlefHandle result = spikard_route_builder_request_timeout(instance, 42);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_rate_limit()¶

Attach a per-route rate limiting configuration, overriding the server-global default.

Signature:

SPIKARDAlefHandle spikard_route_builder_rate_limit(SPIKARDAlefHandle this, SPIKARDAlefHandle rate_limit);

Example:

SPIKARDAlefHandle result = spikard_route_builder_rate_limit(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_request_id()¶

Force per-route request-id generation on or off, overriding the server-global default.

Takes a plain bool rather than RequestIdConfig directly: the wire/metadata type had to become a struct to represent {"enabled": false} (see RequestIdConfig's docs), but this builder is the ergonomic call site (.request_id(true)), so it keeps accepting a bool and wraps it into RequestIdConfig internally in Self.into_metadata.

Signature:

SPIKARDAlefHandle spikard_route_builder_request_id(SPIKARDAlefHandle this, int32_t enabled);

Example:

SPIKARDAlefHandle result = spikard_route_builder_request_id(instance, true);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_jwt_auth()¶

Require JWT authentication for this route.

Signature:

SPIKARDAlefHandle spikard_route_builder_jwt_auth(SPIKARDAlefHandle this, SPIKARDAlefHandle config);

Example:

SPIKARDAlefHandle result = spikard_route_builder_jwt_auth(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_api_key_auth()¶

Require API key authentication for this route.

Signature:

SPIKARDAlefHandle spikard_route_builder_api_key_auth(SPIKARDAlefHandle this, SPIKARDAlefHandle config);

Example:

SPIKARDAlefHandle result = spikard_route_builder_api_key_auth(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_authorization()¶

Attach a roles/scopes/permissions authorization requirement for this route.

Signature:

SPIKARDAlefHandle spikard_route_builder_authorization(SPIKARDAlefHandle this, SPIKARDAlefHandle config);

Example:

SPIKARDAlefHandle result = spikard_route_builder_authorization(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_lifecycle_hooks()¶

Select registered lifecycle hooks to run for this route.

Signature:

SPIKARDAlefHandle spikard_route_builder_lifecycle_hooks(SPIKARDAlefHandle this, SPIKARDAlefHandle hooks);

Example:

SPIKARDAlefHandle result = spikard_route_builder_lifecycle_hooks(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_jsonrpc_method()¶

Expose this route as a JSON-RPC method.

Signature:

SPIKARDAlefHandle spikard_route_builder_jsonrpc_method(SPIKARDAlefHandle this, SPIKARDAlefHandle info);

Example:

SPIKARDAlefHandle result = spikard_route_builder_jsonrpc_method(instance, 0);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_openrpc_spec()¶

Attach a literal OpenRPC method spec document for this route, overriding auto-derivation from the Self.jsonrpc_method metadata when present.

Signature:

SPIKARDAlefHandle spikard_route_builder_openrpc_spec(SPIKARDAlefHandle this, const char* spec);

Example:

SPIKARDAlefHandle result = spikard_route_builder_openrpc_spec(instance, NULL);

Parameters:

Returns: SPIKARDAlefHandle

spikard_route_builder_sync()¶

Mark the route as synchronous.

Signature:

SPIKARDAlefHandle spikard_route_builder_sync(SPIKARDAlefHandle this);

Example:

SPIKARDAlefHandle result = spikard_route_builder_sync(instance);

Returns: SPIKARDAlefHandle

spikard_route_builder_handler_dependencies()¶

Declare the dependency keys that must be resolved before this handler runs.

Signature:

SPIKARDAlefHandle spikard_route_builder_handler_dependencies(SPIKARDAlefHandle this, const char* dependencies);

Example:

SPIKARDAlefHandle result = spikard_route_builder_handler_dependencies(instance, NULL);

Parameters:

Returns: SPIKARDAlefHandle

SPIKARDSchemaConfig¶

C representation: SPIKARDSchemaConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDSchemaConfig does not appear anywhere in the generated header.

Configuration for GraphQL schema building.

Encapsulates all schema-level configuration options including introspection control, complexity limits, and depth limits.

SPIKARDServerConfig¶

C representation: SPIKARDServerConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDServerConfig does not appear anywhere in the generated header.

Server configuration

SPIKARDServerInfo¶

C representation: SPIKARDServerInfo is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDServerInfo does not appear anywhere in the generated header.

Server information

SPIKARDSseEvent¶

C representation: SPIKARDSseEvent is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDSseEvent does not appear anywhere in the generated header.

An individual SSE event

Represents a single Server-Sent Event to be sent to a connected client. Events can have an optional type, ID, and retry timeout for advanced scenarios.

SSE Format¶

Events are serialized to the following text format:

event: event_type
data: {"json":"value"}
id: event-123
retry: 3000

SPIKARDStaticFilesConfig¶

C representation: SPIKARDStaticFilesConfig is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDStaticFilesConfig does not appear anywhere in the generated header.

Static file serving configuration

SPIKARDTestingSseEvent¶

C representation: SPIKARDTestingSseEvent is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDTestingSseEvent does not appear anywhere in the generated header.

A single Server-Sent Event.

SPIKARDUploadFile¶

C representation: SPIKARDUploadFile is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDUploadFile does not appear anywhere in the generated header.

Represents an uploaded file from multipart/form-data requests.

This struct provides efficient access to file content with automatic base64 decoding and implements standard I/O traits for compatibility.

SPIKARDValidateRequest¶

C representation: SPIKARDValidateRequest is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDValidateRequest does not appear anywhere in the generated header.

Request body for POST /asyncapi/validate

SPIKARDValidationResponse¶

C representation: SPIKARDValidationResponse is a documentation-only name for this type. The C ABI hands you a scalar SPIKARDAlefHandle handle -- the literal string SPIKARDValidationResponse does not appear anywhere in the generated header.

Response body for POST /asyncapi/validate

Enums¶

SPIKARDMethod¶

HTTP method

SPIKARDLifecycleHookPhase¶

The five lifecycle phases a hook can be registered against.

Used to resolve a per-route named hook selection (LifecycleHooksConfig in spikard-core.http) against the hooks actually registered on the server: a name is looked up within one specific phase's registered hooks, not across all five, so a hook registered for on_response can never be silently picked up by a route asking for on_request.

SPIKARDSecuritySchemeInfo¶

Security scheme types

Errors¶

SPIKARDAppError¶

Error type for application builder operations.

SPIKARDGraphQlError¶

Errors that can occur during GraphQL operations

These errors are compatible with async-graphql error handling and can be converted to structured HTTP responses matching the project's error fixtures.

SPIKARDSchemaError¶

Error type for schema building operations

Edit this page on GitHub