Skip to content

Build a typed API

This tutorial builds and runs the included web application, then traces one request from a route declaration to a typed JSON response.

  1. RunStart the native server
  2. RequestExercise the route shapes
  3. TraceFollow typed responses

Prerequisite: Install the Incan 0.5 toolchain.

Step 1: Run the hello web example

The repository includes the complete source:

  • Source: examples/web/hello_web.incn
  • GitHub: https://github.com/encero-systems/incan/blob/main/examples/web/hello_web.incn

Build it, then start the server from the Incan repository root:

incan build examples/web/hello_web.incn
incan run examples/web/hello_web.incn

The normal commands reuse the checked std.web, async, and typed-serde closure in the toolchain's full-standard-library Loaf. They do not invoke Cargo on the consumer path.

Step 2: Request the endpoints

With the server running, use another terminal:

curl http://127.0.0.1:8080/
curl http://127.0.0.1:8080/api/greet/World
curl http://127.0.0.1:8080/api/user/42
curl http://127.0.0.1:8080/health

flowchart LR
  A["curl request"] --> B["Incan route"]
  B --> C["typed handler"]
  C --> D["Json response model"]
  D --> E["HTTP response"]

The route selects a typed handler; the response model is serialized at the HTTP boundary.

Route Checked return boundary
/ Response containing HTML
/api/greet/{name} Json[Greeting]
/api/user/{id} Json[User] with an integer path parameter
/health successful Response

The server answers all four routes through checked path-parameter, handler, and response-model boundaries.

Step 3: Trace what you’re seeing

The example demonstrates:

  • @route("/path") for routes (imported from std.web.routing)
  • Json[T] for JSON responses
  • @derive(json) for response models
  • async def handlers (async/await)

Learn more:

You built and ran a native server, exercised four route contracts, and followed one request shape from route selection to a typed response model.

Continue