rest

tinox.core.rest, split out of the bundled stdlib as a standalone tinox-central package.

Client call

import tinox.core.rest.client

class Main
{
    fnc main() -> Int32
    {
        const client: RestClient = RestClient::new("https://api.example.com")
        client.bearerAuth("my-token")

        const response: RestResponse = client.get("/users/42")
        if (response.isOk())
        {
            println("body: " + response.text())
        }
        else
        {
            println("request failed with status " + response.status().toString())
        }

        const created: RestResponse = client.post("/users", "{\"name\":\"Ada\"}")
        created.ensureSuccess()
        println("created: " + created.text())

        return 0
    }
}

Annotated controller

import tinox.core.rest.server
import tinox.core.json

// Annotation-driven: no explicit main()/RestApi anywhere in the program —
// the compiler discovers @ApplicationComponent classes and generates the
// server entry point itself.
@ApplicationComponent
@Path("/api/v1")
class GreetController
{
    @GET
    @Path("/hello/:name")
    @Produces("application/json")
    fn hello(@PathParam name: String, @HttpContext ctx: HttpContext) -> HttpContext
    {
        ctx.response.json("{\"message\":\"Hello, " + name + "!\"}")
        return ctx
    }
}

Annotated controller entry point

import GreetController

// Every Tinox program still needs its own class Main as the mandatory
// entry point (since 2026-08-09) -- @ApplicationComponent's REST server
// spawns and runs alongside it on its own thread, it doesn't replace it.
// This is the required sibling file for the annotated controller above.
class Main
{
    fnc main() -> Int32
    {
        return 0
    }
}

class HttpStatusHelper

* Helper to convert between HttpStatus enum and status code integers

Methods

class MediaTypeHelper

* Helper to convert MediaType enum values to their string representations

Methods

class RequestBuilder

* HTTP request builder for constructing requests * with a fluent API (method chaining pattern) * * Example usage: * RequestBuilder::new("https://api.example.com") * .header("Accept", "application/json") * .get("/users")

Fields

Methods

class RestClient

* REST client for making HTTP requests to RESTful APIs * * Supports building requests with custom headers, * query parameters, and JSON request/response bodies.

Fields

Methods

class RestResponse

* REST response wrapper providing convenient access to * status codes, headers, and parsed JSON bodies

Fields

Methods

class Url

* URL builder utility for constructing URLs with * path segments, query parameters, and fragments

Methods

@annotationclass ApplicationComponent

* Lazy singleton — one instance for the entire lifetime of the application. * Created on first access.

@annotationclass Auth

* Marks a method or class as requiring authentication. * @Auth("bearer") * @Auth("basic")

Fields

Methods

@annotationclass Consumes

* Specifies the accepted request content type. * @Consumes(MediaType::Json)

Fields

Methods

@annotationclass DELETE

* Marks a method as a DELETE endpoint. * @DELETE("/path") or @DELETE for the class base path

Fields

Methods

@annotationclass GET

* Marks a method as a GET endpoint. * @GET("/path") or @GET for the class base path

Fields

Methods

@annotationclass HttpRequestScoped

* One instance per HTTP request. Created fresh for each incoming request * and lives exactly as long as that request.

@annotationclass Inject

* Marks a field for compile-time dependency injection. * The compiler resolves the dependency from the DI container and * wires it up without any runtime lookup. * * Example: * @ApplicationComponent * class UserController * { * @Inject * var service: UserService; * }

class MediaTypeHelper

* Converts MediaType enum values to their MIME type strings.

Methods

@annotationclass OIDCRolesAllowed

* Requires a verified OIDC access token carrying at least one of the * listed realm roles. The Authorization: Bearer <token> header is * verified (RS256 signature via the IdP's JWKS, issuer, audience, * exp/nbf) live against the IdP configured via the OIDC_ISSUER/ * OIDC_JWKS_URI/OIDC_AUDIENCE environment variables -- no key * material or role list is ever hardcoded. * * @OIDCRolesAllowed(["admin", "api-user"]) * fn adminOnly(ctx: HttpContext) -> Nothing { ... }

Fields

Methods

class OidcGuard

Methods

@annotationclass PATCH

* Marks a method as a PATCH endpoint. * @PATCH("/path") or @PATCH for the class base path

Fields

Methods

@annotationclass POST

* Marks a method as a POST endpoint. * @POST("/path") or @POST for the class base path

Fields

Methods

@annotationclass PUT

* Marks a method as a PUT endpoint. * @PUT("/path") or @PUT for the class base path

Fields

Methods

@annotationclass Path

* Sets the base path for a controller class or a path prefix for a method. * @Path("/api/v1")

Fields

Methods

@annotationclass Produces

* Specifies the response content type (Content-Type header). * @Produces(MediaType::Json)

Fields

Methods

class RestApi

* Main REST framework class for building and starting an HTTP API server. * * Combines the annotation-driven approach with explicit registration, * supporting graceful migration once the compiler processes annotations natively. * * Example: * const app: RestApi = RestApi::new(8080); * * // Register an annotated controller * app.register(userController); * * // Or use fluent API directly * app.get("/ping", ctx => { * ctx.response.text("pong"); * }); * * // Add global middleware * app.use(loggingMiddleware); * app.use(corsMiddleware); * * app.start();

Fields

Methods

@Errorclass RestAuthError

* A bearer token was rejected by the OIDC guard.

Fields

class RestController

* Abstract base class for REST controllers. * * Extend this class and use annotations on your methods. * Register the controller with RestApi::register(). * * Example: * @Path("/api/users") * class UserController : RestController * { * @GET("/") * @Produces("application/json") * fn list(ctx: HttpContext) -> Nothing * { * ctx.response.json("[]"); * } * }

Fields

Methods

class RouteEntry

* Represents a registered route with its method, path, handler, * and metadata extracted from annotations.

Fields

Methods

@annotationclass Startup

* Eager singleton — created immediately at application startup, before any * request is handled. Useful for services that need initialization work * (e.g. DB connection pools, background workers).

@annotationclass StatusCode

* Sets the default HTTP status code for the response. * @StatusCode(201)

Fields

Methods

class UrlBuilder

* URL path builder for joining base paths and route paths

Methods