C# API Reference

C# API Reference v0.17.0-rc.11¶

Functions¶

SchemaQueryOnly()¶

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:

public static QueryOnlyConfig SchemaQueryOnly()

Example:

var result = SchemaQueryOnly();

Returns: QueryOnlyConfig

SchemaQueryMutation()¶

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:

public static QueryMutationConfig SchemaQueryMutation()

Example:

var result = SchemaQueryMutation();

Returns: QueryMutationConfig

SchemaFull()¶

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:

public static FullSchemaConfig SchemaFull()

Example:

var result = SchemaFull();

Returns: FullSchemaConfig

Types¶

ApiKeyConfig¶

API Key authentication configuration

AsyncApiConfig¶

AsyncAPI HTTP endpoint configuration

BackgroundJobMetadata¶

Methods¶

CreateDefault()¶

Signature:

public BackgroundJobMetadata CreateDefault()

Example:

var result = BackgroundJobMetadata.CreateDefault();

Returns: BackgroundJobMetadata

BackgroundTaskConfig¶

Configuration for in-process background task execution.

Methods¶

CreateDefault()¶

Signature:

public BackgroundTaskConfig CreateDefault()

Example:

var result = BackgroundTaskConfig.CreateDefault();

Returns: BackgroundTaskConfig

CompressionConfig¶

Compression configuration shared across runtimes

Methods¶

CreateDefault()¶

Signature:

public CompressionConfig CreateDefault()

Example:

var result = CompressionConfig.CreateDefault();

Returns: CompressionConfig

ContactInfo¶

Contact information

CorsConfig¶

CORS configuration for a route

Methods¶

AllowedMethodsJoined()¶

Get the cached joined methods string for preflight responses

Signature:

public string AllowedMethodsJoined()

Example:

var result = instance.AllowedMethodsJoined();

Returns: string

AllowedHeadersJoined()¶

Get the cached joined headers string for preflight responses

Signature:

public string AllowedHeadersJoined()

Example:

var result = instance.AllowedHeadersJoined();

Returns: string

IsOriginAllowed()¶

Check if an origin is allowed (O(1) with wildcard, O(n) for exact match)

Signature:

public bool IsOriginAllowed(string origin)

Example:

var result = instance.IsOriginAllowed("value");

Parameters:

Returns: bool

IsMethodAllowed()¶

Check if a method is allowed (O(1) with wildcard, O(n) for exact match)

Signature:

public bool IsMethodAllowed(string method)

Example:

var result = instance.IsMethodAllowed("value");

Parameters:

Returns: bool

CreateDefault()¶

Signature:

public CorsConfig CreateDefault()

Example:

var result = CorsConfig.CreateDefault();

Returns: CorsConfig

DynamicSchemaConfig¶

Configuration for building and executing a dynamic-SDL schema.

FieldErrorSpec¶

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.

FullSchemaConfig¶

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

Methods¶

CreateDefault()¶

Signature:

public FullSchemaConfig CreateDefault()

Example:

var result = FullSchemaConfig.CreateDefault();

Returns: FullSchemaConfig

GraphQlRouteConfig¶

Configuration for GraphQL routes

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

Methods¶

New()¶

Create a new GraphQL route configuration with defaults

Default values:

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

Signature:

public GraphQlRouteConfig New()

Example:

var result = GraphQlRouteConfig.New();

Returns: GraphQlRouteConfig

Path()¶

Set the HTTP path for the GraphQL endpoint

Signature:

public GraphQlRouteConfig Path(string path)

Example:

var result = instance.Path("value");

Parameters:

Returns: GraphQlRouteConfig

Method()¶

Set the HTTP method for the GraphQL endpoint

Signature:

public GraphQlRouteConfig Method(string method)

Example:

var result = instance.Method("value");

Parameters:

Returns: GraphQlRouteConfig

EnablePlayground()¶

Enable or disable the GraphQL Playground UI

Signature:

public GraphQlRouteConfig EnablePlayground(bool enable)

Example:

var result = instance.EnablePlayground(true);

Parameters:

Returns: GraphQlRouteConfig

Description()¶

Set a custom description for documentation

Signature:

public GraphQlRouteConfig Description(string description)

Example:

var result = instance.Description("value");

Parameters:

Returns: GraphQlRouteConfig

GetPath()¶

Get the configured path

Signature:

public string GetPath()

Example:

var result = instance.GetPath();

Returns: string

GetMethod()¶

Get the configured method

Signature:

public string GetMethod()

Example:

var result = instance.GetMethod();

Returns: string

IsPlaygroundEnabled()¶

Check if playground is enabled

Signature:

public bool IsPlaygroundEnabled()

Example:

var result = instance.IsPlaygroundEnabled();

Returns: bool

GetDescription()¶

Get the description if set

Signature:

public string? GetDescription()

Example:

var result = instance.GetDescription();

Returns: string?

CreateDefault()¶

Signature:

public GraphQlRouteConfig CreateDefault()

Example:

var result = GraphQlRouteConfig.CreateDefault();

Returns: GraphQlRouteConfig

GrpcConfig¶

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).

Methods¶

CreateDefault()¶

Signature:

public GrpcConfig CreateDefault()

Example:

var result = GrpcConfig.CreateDefault();

Returns: GrpcConfig

IntoHandler¶

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

Methods¶

IntoHandler()¶

Convert this value into a shared request handler.

Signature:

public Handler IntoHandler()

Example:

var result = instance.IntoHandler();

Returns: Handler

JsonRpcConfig¶

JSON-RPC server configuration

Methods¶

CreateDefault()¶

Signature:

public JsonRpcConfig CreateDefault()

Example:

var result = JsonRpcConfig.CreateDefault();

Returns: JsonRpcConfig

JsonRpcMethodInfo¶

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.

JwtConfig¶

JWT authentication configuration

LicenseInfo¶

License information

OpenApiConfig¶

OpenAPI configuration

Methods¶

CreateDefault()¶

Signature:

public OpenApiConfig CreateDefault()

Example:

var result = OpenApiConfig.CreateDefault();

Returns: OpenApiConfig

ParseRequest¶

Request body for POST /asyncapi/parse

ParseResult¶

Full parse result returned by POST /asyncapi/parse

ParsedChannel¶

A single channel extracted from an AsyncAPI spec

ParsedMessage¶

A resolved message (name + JSON Schema)

ParsedOperation¶

A single operation extracted from an AsyncAPI spec

ProblemDetails¶

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": [...]
}

Methods¶

WithDetail()¶

Set the detail field

Signature:

public ProblemDetails WithDetail(string detail)

Example:

var result = instance.WithDetail("value");

Parameters:

Returns: ProblemDetails

WithInstance()¶

Set the instance field

Signature:

public ProblemDetails WithInstance(string instance)

Example:

var result = instance.WithInstance("value");

Parameters:

Returns: ProblemDetails

NotFound()¶

Create a not found error

Signature:

public ProblemDetails NotFound(string detail)

Example:

var result = ProblemDetails.NotFound("value");

Parameters:

Returns: ProblemDetails

MethodNotAllowed()¶

Create a method not allowed error

Signature:

public ProblemDetails MethodNotAllowed(string detail)

Example:

var result = ProblemDetails.MethodNotAllowed("value");

Parameters:

Returns: ProblemDetails

InternalServerError()¶

Create an internal server error

Signature:

public ProblemDetails InternalServerError(string detail)

Example:

var result = ProblemDetails.InternalServerError("value");

Parameters:

Returns: ProblemDetails

BadRequest()¶

Create a bad request error

Signature:

public ProblemDetails BadRequest(string detail)

Example:

var result = ProblemDetails.BadRequest("value");

Parameters:

Returns: ProblemDetails

ToJson()¶

Serialize to JSON string

Errors: Returns an error if the serialization fails.

Signature:

public string ToJson()

Example:

var result = instance.ToJson();

Returns: string

Errors: Throws Error.

ToJsonPretty()¶

Serialize to pretty JSON string

Errors: Returns an error if the serialization fails.

Signature:

public string ToJsonPretty()

Example:

var result = instance.ToJsonPretty();

Returns: string

Errors: Throws Error.

QueryMutationConfig¶

Configuration for schemas with Query and Mutation types

Methods¶

CreateDefault()¶

Signature:

public QueryMutationConfig CreateDefault()

Example:

var result = QueryMutationConfig.CreateDefault();

Returns: QueryMutationConfig

QueryOnlyConfig¶

Configuration for schemas with only Query type

Methods¶

CreateDefault()¶

Signature:

public QueryOnlyConfig CreateDefault()

Example:

var result = QueryOnlyConfig.CreateDefault();

Returns: QueryOnlyConfig

RateLimitConfig¶

Rate limiting configuration shared across runtimes

Methods¶

CreateDefault()¶

Signature:

public RateLimitConfig CreateDefault()

Example:

var result = RateLimitConfig.CreateDefault();

Returns: RateLimitConfig

Request¶

Response¶

HTTP Response with custom status code, headers, and content

Methods¶

SetHeader()¶

Set a header

Signature:

public void SetHeader(string key, string value)

Example:

instance.SetHeader("value", "value");

Parameters:

Returns: No return value.

SetCookie()¶

Set a cookie in the response

Signature:

public void SetCookie(string key, string value, bool secure, bool httpOnly, long maxAge, string domain, string path, string sameSite)

Example:

instance.SetCookie("value", "value", true, true, 42, "value", "value", "value");

Parameters:

Returns: No return value.

CreateDefault()¶

Signature:

public Response CreateDefault()

Example:

var result = Response.CreateDefault();

Returns: Response

RouteBuilder¶

Builder for defining a route.

Methods¶

New()¶

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

Signature:

public RouteBuilder New(Method method, string path)

Example:

var result = RouteBuilder.New(new Method(), "value");

Parameters:

Returns: RouteBuilder

HandlerName()¶

Assign an explicit handler name.

Signature:

public RouteBuilder HandlerName(string name)

Example:

var result = instance.HandlerName("value");

Parameters:

Returns: RouteBuilder

RequestSchemaJson()¶

Provide a raw JSON schema for the request body.

Signature:

public RouteBuilder RequestSchemaJson(object schema)

Example:

var result = instance.RequestSchemaJson(new Dictionary<string, object>());

Parameters:

Returns: RouteBuilder

ResponseSchemaJson()¶

Provide a raw JSON schema for the response body.

Signature:

public RouteBuilder ResponseSchemaJson(object schema)

Example:

var result = instance.ResponseSchemaJson(new Dictionary<string, object>());

Parameters:

Returns: RouteBuilder

ParamsSchemaJson()¶

Provide a raw JSON schema for request parameters.

Signature:

public RouteBuilder ParamsSchemaJson(object schema)

Example:

var result = instance.ParamsSchemaJson(new Dictionary<string, object>());

Parameters:

Returns: RouteBuilder

FileParamsJson()¶

Provide multipart file parameter configuration.

Signature:

public RouteBuilder FileParamsJson(object schema)

Example:

var result = instance.FileParamsJson(new Dictionary<string, object>());

Parameters:

Returns: RouteBuilder

Cors()¶

Attach a CORS configuration for this route.

Signature:

public RouteBuilder Cors(CorsConfig cors)

Example:

var result = instance.Cors(new CorsConfig());

Parameters:

Returns: RouteBuilder

Compression()¶

Attach a compression configuration for this route.

Signature:

public RouteBuilder Compression(CompressionConfig compression)

Example:

var result = instance.Compression(new CompressionConfig());

Parameters:

Returns: RouteBuilder

BodyLimit()¶

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

Signature:

public RouteBuilder BodyLimit(nuint maxBytes)

Example:

var result = instance.BodyLimit(42);

Parameters:

Returns: RouteBuilder

RequestTimeout()¶

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

Signature:

public RouteBuilder RequestTimeout(ulong seconds)

Example:

var result = instance.RequestTimeout(42);

Parameters:

Returns: RouteBuilder

Sync()¶

Mark the route as synchronous.

Signature:

public RouteBuilder Sync()

Example:

var result = instance.Sync();

Returns: RouteBuilder

HandlerDependencies()¶

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

Signature:

public RouteBuilder HandlerDependencies(List<string> dependencies)

Example:

var result = instance.HandlerDependencies(new List<object>());

Parameters:

Returns: RouteBuilder

SchemaConfig¶

Configuration for GraphQL schema building.

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

Methods¶

CreateDefault()¶

Signature:

public SchemaConfig CreateDefault()

Example:

var result = SchemaConfig.CreateDefault();

Returns: SchemaConfig

ServerConfig¶

Server configuration

Methods¶

CreateDefault()¶

Signature:

public ServerConfig CreateDefault()

Example:

var result = ServerConfig.CreateDefault();

Returns: ServerConfig

ServerInfo¶

Server information

SseEvent¶

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

Methods¶

WithId()¶

Set the event ID for client-side reconnection support

Sets an ID that clients can use to resume from this point if they disconnect. The client sends this ID back in the Last-Event-ID header when reconnecting.

Signature:

public SseEvent WithId(string id)

Example:

var result = instance.WithId("value");

Parameters:

Returns: SseEvent

WithRetry()¶

Set the retry timeout for client reconnection

Sets the time in milliseconds clients should wait before attempting to reconnect if the connection is lost. The client browser will automatically handle reconnection.

Signature:

public SseEvent WithRetry(ulong retryMs)

Example:

var result = instance.WithRetry(42);

Parameters:

Returns: SseEvent

StaticFilesConfig¶

Static file serving configuration

TestingSseEvent¶

A single Server-Sent Event.

UploadFile¶

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.

Methods¶

AsBytes()¶

Get the raw file content as bytes.

This provides zero-copy access to the underlying buffer.

Signature:

public byte[] AsBytes()

Example:

var result = instance.AsBytes();

Returns: byte[]

ReadToString()¶

Read the file content as a UTF-8 string.

Errors:

Returns an error if the content is not valid UTF-8.

Signature:

public string ReadToString()

Example:

var result = instance.ReadToString();

Returns: string

Errors: Throws Error.

ContentTypeOrDefault()¶

Get the content type, defaulting to "application/octet-stream".

Signature:

public string ContentTypeOrDefault()

Example:

var result = instance.ContentTypeOrDefault();

Returns: string

ValidateRequest¶

Request body for POST /asyncapi/validate

ValidationResponse¶

Response body for POST /asyncapi/validate

Enums¶

Method¶

HTTP method

SecuritySchemeInfo¶

Security scheme types

Errors¶

AppError¶

Error type for application builder operations.

GraphQlError¶

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.

SchemaError¶

Error type for schema building operations

Edit this page on GitHub