Skip to content

Build your first API (tutorial)

This tutorial walks you through running the built-in web framework and serving a JSON endpoint.

Prerequisite: Install, build, and run.

If something fails

If you hit errors while building/running, start with Troubleshooting. If it still looks like a bug, please file an issue on GitHub.

Step 1: Run the hello web example

The repo includes a runnable example:

  • Source: examples/web/hello_web.incn
  • GitHub: https://github.com/dannys-code-corner/incan/blob/main/examples/web/hello_web.incn

Build it:

incan build examples/web/hello_web.incn

No-install fallback

If you did not run make install, you can still run the incan binary directly:

  • from the repository root:
./target/release/incan ...
  • or via an absolute path (from anywhere):
/absolute/path/to/incan run path/to/file.incn

Note: the first build may download Rust crates via Cargo (can take minutes) and requires internet access.

Run the compiled binary:

./target/incan/hello_web/target/release/hello_web

Step 2: Hit the endpoints

In another terminal:

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

Step 3: Understand what you’re seeing

The example demonstrates:

  • @route("/path") for routes
  • Json[T] for JSON responses
  • @derive(Serialize) for response models
  • async def handlers (async/await)

Learn more: